claude-code-builder

Claude Code Builder

一体化Claude Code资源构建工具

轻松创建Commands和Subagents - 一次调用，直接安装到项目中

🎯 核心特点

• 🚀 一体化API - 一次调用完成命令生成+安装，无需分步操作
• ⚙️ 参数映射 - 直接对应Claude Code的frontmatter配置，学习成本为零
• 🎯 统一格式 - 所有命令都用标准Claude Code格式，兼容性优秀
• ✅ 结果明确 - 清晰的成功/失败反馈，知道每一步的执行结果
• 🔒 类型安全 - 完整TypeScript支持，IDE智能提示和类型检查
• 🛠️ 错误友好 - 详细的错误信息和参数验证，便于调试
• 📦 轻量级 - 零外部依赖，只使用Node.js内置模块

📦 安装

npm install claude-code-builder

🚀 快速开始

import { ClaudeCodeBuilder } from 'claude-code-builder';

// 创建并安装一个Claude Code命令
const result = await ClaudeCodeBuilder.createCommand({
  name: 'translator',
  content: '你是专业翻译专家，请翻译以下内容：$ARGUMENTS',
  description: '多语言翻译专家',
  argumentHint: '[待翻译文本]'
});

if (result.success) {
  console.log(`✅ ${result.message}`);
  // 现在可以在Claude Code中使用 /translator 命令了！
} else {
  console.error(`❌ ${result.error}`);
}

📖 完整API参考

核心方法

ClaudeCodeBuilder.createCommand(options)

创建并安装Claude Code命令。生成标准的Claude Code格式（带YAML frontmatter），支持所有Claude Code功能。

ClaudeCodeBuilder.createSubagent(options)

创建并安装Claude Code Subagent。生成标准的Claude Code Subagent格式，支持专业化AI助手。

参数：

interface CommandOptions {
  // 必需参数
  name: string;           // 命令名称
  content: string;        // 提示词内容

  // 可选参数（对应Claude Code frontmatter）
  description?: string;   // 命令描述
  model?: string;         // Claude模型
  argumentHint?: string;  // 参数提示
  allowedTools?: string[]; // 允许的工具
  customFields?: Record<string, any>; // 自定义frontmatter字段
  
  // 工具参数
  targetDir?: string;     // 安装目录（默认 ./.claude/commands）
}

返回值：

interface CommandResult {
  success: boolean;         // 是否成功
  commandName: string;      // 命令名
  filePath?: string;        // 文件路径（成功时）
  message: string;          // 结果消息
  error?: string;           // 错误信息（失败时）
  generatedContent?: string; // 生成的内容（调试用）
}

Subagent参数：

interface SubagentOptions {
  // 必需参数
  name: string;                // Subagent名称
  description: string;         // 何时调用此subagent的描述
  content: string;             // System prompt内容

  // 可选参数
  tools?: string[];            // 允许的工具列表（省略则继承所有工具）
  targetDir?: string;          // 安装目录（默认 ./.claude/agents）
}

Subagent返回值：

interface SubagentResult {
  success: boolean;            // 是否成功
  subagentName: string;        // Subagent名称
  filePath?: string;           // 文件路径（成功时）
  message: string;             // 结果消息
  error?: string;              // 错误信息（失败时）
  generatedContent?: string;   // 生成的内容（调试用）
}

导出的类型

export type { CommandOptions, CommandResult, SubagentOptions, SubagentResult } from 'claude-code-builder';

💡 详细使用示例

基础命令创建

import { ClaudeCodeBuilder } from 'claude-code-builder';

const result = await ClaudeCodeBuilder.createCommand({
  name: 'code-reviewer',
  content: `你是代码审查专家，拥有多年的代码质量管控经验。

请对以下代码进行专业审查：$ARGUMENTS

重点关注：
1. 代码质量和可读性
2. 潜在的bug和安全问题
3. 性能优化机会
4. 最佳实践遵循情况

请提供具体的改进建议。`,
  description: '专业代码审查助手',
  argumentHint: '[代码文件或代码片段]'
});

console.log(result.success ? '✅ 代码审查专家已安装' : `❌ ${result.error}`);

生成的文件 .claude/commands/code-reviewer.md：

---
description: "专业代码审查助手"
argument-hint: "[代码文件或代码片段]"
---

你是代码审查专家，拥有多年的代码质量管控经验。

请对以下代码进行专业审查：$ARGUMENTS

重点关注：
1. 代码质量和可读性
2. 潜在的bug和安全问题
3. 性能优化机会
4. 最佳实践遵循情况

请提供具体的改进建议。

高级配置命令

const result = await ClaudeCodeBuilder.createCommand({
  name: 'api-designer',
  content: `你是API设计专家，专精于RESTful API和GraphQL设计。

设计任务：$ARGUMENTS

请提供：
1. API架构设计
2. 端点规划
3. 数据模型设计
4. 错误处理策略
5. 安全考虑`,
  description: 'API架构设计顾问',
  model: 'claude-3-5-sonnet-20241022',
  argumentHint: '[API需求描述]',
  allowedTools: ['Read', 'Write', 'Bash'],
  customFields: {
    category: 'architecture',
    expertise: 'api-design',
    version: '1.0'
  }
});

生成的文件 .claude/commands/api-designer.md：

---
description: "API架构设计顾问"
argument-hint: "[API需求描述]"
model: "claude-3-5-sonnet-20241022"
allowed-tools:
  - "Read"
  - "Write"
  - "Bash"
category: "architecture"
expertise: "api-design"
version: "1.0"
---

你是API设计专家，专精于RESTful API和GraphQL设计。

设计任务：$ARGUMENTS

请提供：
1. API架构设计
2. 端点规划
3. 数据模型设计
4. 错误处理策略
5. 安全考虑

批量命令创建

const experts = [
  { name: 'frontend-dev', content: '你是前端开发专家，精通React、Vue、Angular...', description: '前端开发专家' },
  { name: 'backend-dev', content: '你是后端开发专家，精通Node.js、Python、Java...', description: '后端开发专家' },
  { name: 'devops-expert', content: '你是DevOps专家，精通Docker、K8s、CI/CD...', description: 'DevOps运维专家' },
  { name: 'ui-designer', content: '你是UI/UX设计师，精通用户体验和界面设计...', description: 'UI/UX设计师' }
];

console.log('🚀 批量安装开发团队专家命令...');

for (const expert of experts) {
  const result = await ClaudeCodeBuilder.createCommand({
    name: expert.name,
    content: expert.content,
    description: expert.description,
    argumentHint: '[项目需求或问题描述]'
  });
  
  console.log(result.success ? `✅ ${expert.name}` : `❌ ${expert.name}: ${result.error}`);
}

console.log('🎉 团队专家命令安装完成！所有命令都采用标准Claude Code格式！');

Subagent创建

基础Subagent创建

import { ClaudeCodeBuilder } from 'claude-code-builder';

const result = await ClaudeCodeBuilder.createSubagent({
  name: 'code-reviewer',
  description: 'Expert code review specialist. Use immediately after writing or modifying code.',
  content: `You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)`,
  tools: ['Read', 'Grep', 'Glob', 'Bash']
});

console.log(result.success ? '✅ 代码审查专家安装成功' : `❌ ${result.error}`);

生成的文件 .claude/agents/code-reviewer.md：

---
name: code-reviewer
description: Expert code review specialist. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

无工具限制的Subagent

const result = await ClaudeCodeBuilder.createSubagent({
  name: 'general-helper',
  description: 'General purpose assistant for various tasks. Use when no specific expertise is needed.',
  content: 'You are a helpful general assistant. Provide clear, accurate, and actionable responses to user queries.'
  // 注意：没有指定tools，将继承所有可用工具
});

批量Subagent创建

const subagents = [
  {
    name: 'debugger',
    description: 'Debugging specialist for errors and failures. Use when encountering issues.',
    content: 'You are an expert debugger. Analyze errors systematically and provide solutions.',
    tools: ['Read', 'Edit', 'Bash', 'Grep']
  },
  {
    name: 'test-runner',
    description: 'Test automation expert. Use to run tests and fix failures.',
    content: 'You are a test automation expert. Run appropriate tests and fix any failures.',
    tools: ['Bash', 'Read', 'Edit']
  },
  {
    name: 'performance-optimizer',
    description: 'Performance analysis and optimization specialist.',
    content: 'You are a performance expert. Identify bottlenecks and suggest optimizations.',
    tools: ['Read', 'Bash', 'WebSearch']
  }
];

console.log('🚀 批量安装开发团队Subagent...');

for (const subagent of subagents) {
  const result = await ClaudeCodeBuilder.createSubagent(subagent);
  console.log(result.success ? `✅ ${subagent.name}` : `❌ ${subagent.name}: ${result.error}`);
}

console.log('🎉 所有专业Subagent安装完成！');

自定义安装目录

// 安装到自定义目录
const result = await ClaudeCodeBuilder.createCommand({
  name: 'project-expert',
  content: '你是项目专家...',
  targetDir: './my-custom-commands'  // 自定义安装位置
});

错误处理

const result = await ClaudeCodeBuilder.createCommand({
  name: '',  // 错误：空名称
  content: '内容'
});

if (!result.success) {
  console.error('命令创建失败：', result.error);
  // 输出: "命令创建失败：命令名称是必需的"
}

🛠️ 集成示例

与PromptX集成

// 假设从PromptX获取角色内容
import { promptx } from 'promptx';
import { ClaudeCodeBuilder } from 'claude-code-builder';

async function exportPromptXRole(roleId) {
  const roleContent = await promptx.getRole(roleId);
  
  const result = await ClaudeCodeBuilder.createCommand({
    name: roleId,
    content: roleContent,
    description: `PromptX ${roleId} 专家`,
    customFields: {
      source: 'promptx',
      exported: new Date().toISOString()
    }
  });
  
  return result;
}

与配置文件集成

import fs from 'fs/promises';

// 从配置文件批量创建命令
async function installFromConfig(configFile) {
  const config = JSON.parse(await fs.readFile(configFile, 'utf8'));
  
  for (const commandConfig of config.commands) {
    const result = await ClaudeCodeBuilder.createCommand(commandConfig);
    console.log(result.success ? `✅ ${commandConfig.name}` : `❌ ${result.error}`);
  }
}

配置文件示例 commands-config.json：

{
  "commands": [
    {
      "name": "product-manager",
      "content": "你是资深产品经理...",
      "description": "产品策略顾问",
      "model": "claude-3-5-sonnet-20241022"
    },
    {
      "name": "tech-lead",
      "content": "你是技术负责人...",
      "description": "技术架构顾问"
    }
  ]
}

📋 支持的Claude Code功能

Frontmatter字段对应

工具包参数	Claude Code字段	说明
description	description	命令描述
model	model	指定Claude模型
argumentHint	argument-hint	参数提示
allowedTools	allowed-tools	允许的工具列表
customFields	任意字段	自定义frontmatter字段

Claude Code变量支持

生成的命令支持所有Claude Code内置变量：

• $ARGUMENTS - 用户输入的所有参数
• $1, $2, $3... - 单个参数
• @filename - 引用项目文件
• !command - 执行bash命令

🔧 最佳实践

1. 命令命名规范

// ✅ 推荐
await ClaudeCodeBuilder.createCommand({
  name: 'code-reviewer',    // 短横线分隔，清晰描述功能
  name: 'api-designer',     // 领域+角色的组合
  name: 'sql-optimizer'     // 技术栈+功能
});

// ❌ 避免
await ClaudeCodeBuilder.createCommand({
  name: 'my awesome tool',  // 包含空格会被自动转换
  name: 'tool',             // 过于通用
  name: 'helper@123'        // 包含特殊字符会被转换
});

注意: 包含空格或特殊字符的名称会被自动转换为安全的文件名格式。

2. 内容结构化

const content = `你是${role}专家，拥有${experience}。

任务：$ARGUMENTS

请提供：
1. 问题分析
2. 解决方案
3. 最佳实践建议
4. 相关资源推荐

回答要求：
- 结构化输出
- 提供具体示例
- 给出可执行的建议`;

3. 参数提示清晰化

await ClaudeCodeBuilder.createCommand({
  name: 'code-reviewer',
  argumentHint: '[代码文件路径或代码片段]',  // ✅ 清晰
  // argumentHint: '[输入]',                  // ❌ 模糊
});

4. 错误处理

async function safeCreateCommand(options) {
  try {
    const result = await ClaudeCodeBuilder.createCommand(options);
    
    if (result.success) {
      console.log(`✅ 命令 ${result.commandName} 安装成功`);
      return result;
    } else {
      console.error(`❌ 安装失败: ${result.error}`);
      return null;
    }
  } catch (error) {
    console.error(`💥 意外错误: ${error.message}`);
    return null;
  }
}

🚨 常见问题

Q: 生成的命令文件在哪里？

A: 默认在 .claude/commands/ 目录下，可通过 targetDir 参数自定义。

Q: 如何在Claude Code中使用生成的命令？

A: 直接输入 /命令名 即可，例如 /translator 翻译这段文字。

Q: 支持中文命令名吗？

A: 支持中文，但会自动转换为安全的文件名格式。

Q: 可以覆盖现有命令吗？

A: 可以，工具会自动覆盖同名文件。

Q: 如何删除已安装的命令？

A: 直接删除对应的 .md 文件即可。

🤝 贡献指南

我们欢迎所有形式的贡献！请参阅 CONTRIBUTING.md 了解详细信息。

开发设置

git clone https://github.com/your-org/claude-code-builder.git
cd claude-code-builder
npm install
npm run build
npm test

📄 许可证

MIT License © 2024 Claude Command Toolkit Team

🔗 相关资源

• Claude Code 官方文档
• Claude Code Slash Commands
• PromptX 项目

⭐ 给个星标 | 📖 查看文档 | 🐛 报告问题