tool-creator

工具创建器

在 .claude/tools/<category>/ 中创建可执行工具文件。工具按 cli、analysis、validation、integrations 等类别组织。

步骤 0：检查是否已有工具

创建前，检查工具是否已存在：

find .claude/tools/ -name "<tool-name>.*" -type f

如果已存在 → 使用 Read 检查当前工具文件，然后使用 Edit 直接应用更改。更新后，运行创建后集成步骤（步骤 4）。

如果是新工具 → 继续执行步骤 0.1。

步骤 0.1：智能重复项检测（必需）

继续创建前，运行 3 层重复项检查：

const { checkDuplicate } = require('.claude/lib/creation/duplicate-detector.cjs');
const result = checkDuplicate({
  artifactType: 'tool',
  name: proposedName,
  description: proposedDescription,
  keywords: proposedKeywords || [],
});

处理结果：

• EXACT_MATCH：停止创建。改用 tool-updater 技能：Skill({ skill: 'tool-updater' })
• REGISTRY_MATCH：警告用户——此产物已注册，但文件可能缺失。创建前先调查并请用户确认。
• SIMILAR_FOUND：显示候选项及其分数。询问用户：“存在相似产物。要继续创建，还是更新现有产物？”
• NO_MATCH：继续下一步。

覆盖选项：如果用户明确传入 --force，则完全跳过此检查。

---

步骤 0.5：配套项检查

继续创建前，运行生态系统配套项检查：

1. 使用 .claude/lib/creators/companion-check.cjs 中的 companion-check.cjs
2. 调用 checkCompanions("tool", "{tool-name}") 以识别配套产物
3. 检查配套项清单——记录缺失的必需或推荐配套项
4. 计划在此产物完成后创建或验证缺失的配套项
5. 在创建后集成说明中包含配套项检查结果

此步骤仅供参考（不会阻止创建），但可确保充分考虑整个产物生态系统。

使用场景

• 创建可复用的命令行实用程序
• 构建分析或验证脚本
• 实现框架自动化工具
• 添加工作流集成实用程序

工具文件格式

工具是 CommonJS 或 ESM 模块，包含：

#!/usr/bin/env node
/**
 * Tool Name - Brief description
 *
 * Usage:
 *   node .claude/tools/<category>/<tool-name>.cjs [options]
 *
 * Options:
 *   --help     Show help
 *   --option   Description
 */

const main = async () => {
  // Tool implementation
};

if (require.main === module) {
  main().catch(console.error);
}

module.exports = { main };

工具类别

类别	用途	示例
cli	命令行实用程序	验证器、格式化器
analysis	代码分析工具	复杂度、依赖项
validation	验证脚本	架构、lint
integrations	外部集成工具	API 客户端、webhook
maintenance	框架维护	清理、迁移
optimization	性能优化	索引、缓存
runtime	运行时实用程序	配置读取器、加载器
visualization	图表和关系图生成	mermaid、graphviz
workflow	工作流自动化	任务运行器、编排器
gates	质量门禁和检查	覆盖率、安全性
context	上下文管理	压缩、交接

创建工作流

步骤 1：验证输入

// Validate tool name (lowercase, hyphens, no spaces)
const toolName = args.name.toLowerCase().replace(/[^a-z0-9-]/g, '-');

// Validate category exists
const validCategories = [
  'cli',
  'analysis',
  'validation',
  'integrations',
  'maintenance',
  'optimization',
  'runtime',
  'visualization',
  'workflow',
  'gates',
  'context',
];

if (!validCategories.includes(args.category)) {
  throw new Error(`Invalid category. Must be one of: ${validCategories.join(', ')}`);
}

步骤 2：创建工具文件

const toolPath = `.claude/tools/${args.category}/${toolName}.cjs`;

// Create tool directory if it doesn't exist
await mkdir(`.claude/tools/${args.category}`, { recursive: true });

// Generate tool content
const content = `#!/usr/bin/env node
/**
 * ${toolName.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase())} - ${args.description || 'Tool description'}
 *
 * Usage:
 *   node .claude/tools/${args.category}/${toolName}.cjs [options]
 *
 * Options:
 *   --help     Show this help message
 */

${args.implementation}

if (require.main === module) {
  main().catch(console.error);
}

module.exports = { main };
`;

await writeFile(toolPath, content);

// Make executable (Unix-like systems)
if (process.platform !== 'win32') {
  await chmod(toolPath, '755');
}

步骤 3：更新工具目录

const catalogPath = '.claude/context/artifacts/catalogs/tool-catalog.md';

// Add entry to catalog under appropriate category
const newEntry = `| ${toolName} | ${args.description} | .claude/tools/${args.category}/${toolName}.cjs | active |`;

// Insert into catalog preserving category structure

步骤 4：运行创建后集成

const {
  runIntegrationChecklist,
  queueCrossCreatorReview,
} = require('.claude/lib/creators/creator-commons.cjs');

await runIntegrationChecklist('tool', toolPath);
await queueCrossCreatorReview('tool', toolPath, {
  artifactName: toolName,
  createdBy: 'tool-creator',
  category: args.category,
});

创建后集成

创建工具后，运行集成检查清单：

const {
  runIntegrationChecklist,
  queueCrossCreatorReview,
} = require('.claude/lib/creators/creator-commons.cjs');

// 1. Run integration checklist
const result = await runIntegrationChecklist('tool', '.claude/tools/<category>/<tool-name>.cjs');

// 2. Queue cross-creator review
await queueCrossCreatorReview('tool', '.claude/tools/<category>/<tool-name>.cjs', {
  artifactName: '<tool-name>',
  createdBy: 'tool-creator',
  category: '<category>',
});

// 3. Review impact report
// Check result.mustHave for failures - address before marking complete

集成验证：

• 工具已添加到正确类别下的 tool-catalog.md
• 工具文件可执行（Unix）或可运行（Windows）
• 工具包含帮助文本和用法示例
• 工具通过基本冒烟测试

用法示例

创建验证工具

Skill({
  skill: 'tool-creator',
  args: `--name schema-validator --category validation --implementation "
const validateSchema = async () => {
  console.log('Validating schema...');
};

const main = async () => {
  await validateSchema();
};
"`,
});

创建分析工具

Skill({
  skill: 'tool-creator',
  args: `--name complexity-analyzer --category analysis --implementation "
const analyzeComplexity = async (filePath) => {
  console.log('Analyzing complexity for:', filePath);
};

const main = async () => {
  const [,, filePath] = process.argv;
  await analyzeComplexity(filePath);
};
"`,
});

相关技能

• skill-creator - 创建调用工具的技能
• hook-creator - 创建封装工具执行的前置/后置钩子

铁律

1. 每个产物都必须有配套的 schema — 没有 schema 的工具就没有契约；使用者无法验证输入/输出。为该工具的 CLI 接口在 .claude/schemas/ 中创建 JSON schema。
2. 每个产物都必须关联至少一个 Agent — 未分配给任何 Agent 的工具永远不会被调用。通过相关 Agent 的 tools: frontmatter 数组为其分配该工具。
3. 每个产物都必须编入目录索引 — 未列入 tool-catalog.md 的工具无法被发现。在 .claude/context/artifacts/catalogs/tool-catalog.md 的正确类别下添加条目。
4. 每个产物都必须通过集成验证 — 在标记创建完成前，运行 node .claude/tools/cli/validate-integration.cjs <tool-path>。未通过验证的工具存在失效引用。
5. 每个产物都必须记录一条记忆 — 将工具创建模式、决策和任何问题写入 .claude/context/memory/（learnings.md、decisions.md、issues.md）。没有记忆，后续会话就无法看到这次创建。

记忆协议（强制）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新工具模式 → .claude/context/memory/learnings.md
• 工具创建问题 → .claude/context/memory/issues.md
• 类别决策 → .claude/context/memory/decisions.md

假设可能随时中断：如果没有记录在记忆中，就等于没有发生。

交叉引用：创建者生态

此技能属于创建者生态。研究发现缺口时，调用相应的配套创建者：

发现的缺口	所需产物	要调用的创建者	调用时机
领域知识需要可复用的技能	技能	Skill({ skill: 'skill-creator' })	缺口涵盖完整的技能领域
现有技能的覆盖不完整	技能更新	Skill({ skill: 'skill-updater' })	存在相关技能，但覆盖不完整
某项能力需要专属 Agent	Agent	Skill({ skill: 'agent-creator' })	需要 Agent 负责该能力
现有 Agent 需要更新能力	Agent 更新	Skill({ skill: 'agent-updater' })	存在相关 Agent，但能力不完整
领域需要代码/项目脚手架	模板	Skill({ skill: 'template-creator' })	需要可复用的代码模式
行为需要前置/后置执行守卫	钩子	Skill({ skill: 'hook-creator' })	需要强制执行行为
流程需要多阶段编排	工作流	Skill({ skill: 'workflow-creator' })	需要多步骤协同
产物需要结构化 I/O 验证	schema	Skill({ skill: 'schema-creator' })	需要产物 I/O 的 JSON schema
用户交互需要斜杠命令	命令	Skill({ skill: 'command-creator' })	需要面向用户的快捷方式
重复逻辑需要可复用的 CLI 工具	工具	Skill({ skill: 'tool-creator' })	需要 CLI 实用工具
仅限狭窄/单一产物的能力	内联	仅在此产物中记录	太具体，无法泛化

---

生态系统对齐契约（强制）

此创建者技能属于协同运作的创建者生态系统。在此创建的任何产物都必须与相关创建者保持一致并通过验证：

• agent-creator：负责所有权和执行路径
• skill-creator：负责能力打包和分配
• tool-creator：负责可执行的自动化界面
• hook-creator：负责执行与防护措施
• rule-creator 和 semgrep-rule-creator：负责策略和静态检查
• template-creator：负责标准化脚手架
• workflow-creator：负责编排和阶段门控
• command-creator：负责用户／操作员命令 UX

跨创建者交接（必需）

完成前，请验证所有相关交接：

1. .claude/CLAUDE.md 和相关路由文档中存在产物路由。
2. 已更新发现／注册表条目（适用时包括目录／索引／注册表）。
3. 已创建配套产物，或明确说明豁免原因。
4. 针对所创建的产物，validate-integration.cjs 检查通过。
5. 技能元数据变更时，重新生成技能索引。

研究门控（Exa + arXiv — 两者均为强制要求）

对于新模式、模板或工作流，必须开展研究：

1. 使用 Exa 研究实现方式和生态系统模式：
   • mcp__Exa__web_search_exa({ query: '<topic> 2025 best practices' })
   • mcp__Exa__get_code_context_exa({ query: '<topic> implementation examples' })
2. 搜索 arXiv 上的学术研究（AI／ML、Agent、评估、编排、记忆／RAG、安全相关主题必须执行）：
   • 通过 Exa：mcp__Exa__web_search_exa({ query: 'site:arxiv.org <topic> 2024 2025' })
   • 直接 API：WebFetch({ url: 'https://arxiv.org/search/?query=<topic>&searchtype=all&start=0' })
3. 在产物引用／文档中记录决策、约束和非目标。
4. 尽量减少更新，避免过度设计。

主题涉及以下内容时，必须搜索 arXiv（不可作为备用选项）： AI Agent、大模型评估、编排、记忆／RAG、安全、静态分析或任何新兴方法。

回归安全交付

• 行为变更严格遵循 RED -> GREEN -> REFACTOR。
• 对变更的模块运行针对性测试。
• 对变更的文件运行 lint／format。
• 按关注点划分提交（逻辑／文档／生成的产物）。

可选：评估质量门控

运行共享评估框架，以验证工具质量：

node .claude/skills/skill-creator/scripts/eval-runner.cjs --skill tool-creator

工具产物的评分器断言：

• --help 响应：工具对 --help（或 -h）作出响应，显示用法摘要，其中包含必需／可选参数以及至少一个调用示例
• 子进程使用 shell: false：任何 child_process.spawn 或 execFile 调用都使用 shell: false 和数组参数（根据 SE-security 规则，绝不使用 shell: true）
• 优雅处理缺失输入：缺少必需参数时，工具以非零代码退出并显示人类可读的错误消息；不得出现未处理异常或崩溃转储
• 存在目录条目：工具已在 .claude/context/artifacts/catalogs/tool-catalog.md 中注册，包含类别、描述和接线状态
• 超时安全：长时间运行的操作设有明确超时；输入缺失时不会陷入无限循环

完整评估流程以及评分器／分析器 Agent 的用法，请参阅 .claude/skills/skill-creator/EVAL_WORKFLOW.md。