tool-creator

Tool Creator

Create executable tool files in .claude/tools/<category>/. Tools are organized into categories like cli, analysis, validation, integrations, etc.

Step 0: Check for Existing Tool

Before creating, check if tool already exists:

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

If EXISTS → use Read to inspect the current tool file, then Edit to apply changes directly. Run the post-creation integration steps (Step 4) after updating.

If NEW → continue with Step 0.1.

Step 0.1: Smart Duplicate Detection (MANDATORY)

Before proceeding with creation, run the 3-layer duplicate check:

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

Handle results:

• EXACT_MATCH: Stop creation. Route to tool-updater skill instead: Skill({ skill: 'tool-updater' })
• REGISTRY_MATCH: Warn user — artifact is registered but file may be missing. Investigate before creating. Ask user to confirm.
• SIMILAR_FOUND: Display candidates with scores. Ask user: "Similar artifact(s) exist. Continue with new creation or update existing?"
• NO_MATCH: Proceed to next step.

Override: If user explicitly passes --force, skip this check entirely.

---

Step 0.5: Companion Check

Before proceeding with creation, run the ecosystem companion check:

1. Use companion-check.cjs from .claude/lib/creators/companion-check.cjs
2. Call checkCompanions("tool", "{tool-name}") to identify companion artifacts
3. Review the companion checklist — note which required/recommended companions are missing
4. Plan to create or verify missing companions after this artifact is complete
5. Include companion findings in post-creation integration notes

This step is informational (does not block creation) but ensures the full artifact ecosystem is considered.

When to Use

• Creating reusable command-line utilities
• Building analysis or validation scripts
• Implementing framework automation tools
• Adding workflow integration utilities

Tool File Format

Tools are CommonJS or ESM modules with:

#!/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 };

Tool Categories

Category	Purpose	Examples
cli	Command-line utilities	validators, formatters
analysis	Code analysis tools	complexity, dependencies
validation	Validation scripts	schema, lint
integrations	External integration tools	API clients, webhooks
maintenance	Framework maintenance	cleanup, migration
optimization	Performance optimization	indexing, caching
runtime	Runtime utilities	config readers, loaders
visualization	Diagram and graph generation	mermaid, graphviz
workflow	Workflow automation	task runners, orchestrators
gates	Quality gates and checks	coverage, security
context	Context management	compression, handoff

Creation Workflow

Step 1: Validate Inputs

// 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(', ')}`);
}

Step 2: Create Tool File

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');
}

Step 3: Update Tool Catalog

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

Step 4: Run Post-Creation Integration

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,
});

Post-Creation Integration

After tool creation, run integration checklist:

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

Integration verification:

• Tool added to tool-catalog.md under correct category
• Tool file is executable (Unix) or runnable (Windows)
• Tool has help text and usage examples
• Tool passes basic smoke test

Usage Examples

Create Validation Tool

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

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

Create Analysis Tool

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);
};
"`,
});

Related Skills

• skill-creator - Create skills that invoke tools
• hook-creator - Create pre/post hooks that wrap tool execution

Iron Laws

1. Every artifact MUST have a companion schema — Tools without a schema have no contract; consumers cannot validate inputs/outputs. Create a JSON schema in .claude/schemas/ for the tool's CLI interface.
2. Every artifact MUST be wired to at least one agent — A tool not assigned to any agent is never invoked. Assign the tool to relevant agents via their tools: frontmatter array.
3. Every artifact MUST be indexed in its catalog — Tools not in tool-catalog.md are invisible to discovery. Add an entry to .claude/context/artifacts/catalogs/tool-catalog.md under the correct category.
4. Every artifact MUST pass integration validation — Run node .claude/tools/cli/validate-integration.cjs <tool-path> before marking creation complete. A tool that fails validation has broken references.
5. Every artifact MUST record a memory entry — Write the tool creation pattern, decisions, and any issues to .claude/context/memory/ (learnings.md, decisions.md, issues.md). Without memory, the creation is invisible to future sessions.

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New tool pattern → .claude/context/memory/learnings.md
• Tool creation issue → .claude/context/memory/issues.md
• Category decision → .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

Cross-Reference: Creator Ecosystem

This skill is part of the Creator Ecosystem. When research uncovers gaps, trigger the appropriate companion creator:

Gap Discovered	Required Artifact	Creator to Invoke	When
Domain knowledge needs a reusable skill	skill	Skill({ skill: 'skill-creator' })	Gap is a full skill domain
Existing skill has incomplete coverage	skill update	Skill({ skill: 'skill-updater' })	Close skill exists but incomplete
Capability needs a dedicated agent	agent	Skill({ skill: 'agent-creator' })	Agent to own the capability
Existing agent needs capability update	agent update	Skill({ skill: 'agent-updater' })	Close agent exists but incomplete
Domain needs code/project scaffolding	template	Skill({ skill: 'template-creator' })	Reusable code patterns needed
Behavior needs pre/post execution guards	hook	Skill({ skill: 'hook-creator' })	Enforcement behavior required
Process needs multi-phase orchestration	workflow	Skill({ skill: 'workflow-creator' })	Multi-step coordination needed
Artifact needs structured I/O validation	schema	Skill({ skill: 'schema-creator' })	JSON schema for artifact I/O
User interaction needs a slash command	command	Skill({ skill: 'command-creator' })	User-facing shortcut needed
Repeated logic needs a reusable CLI tool	tool	Skill({ skill: 'tool-creator' })	CLI utility needed
Narrow/single-artifact capability only	inline	Document within this artifact only	Too specific to generalize

---

Ecosystem Alignment Contract (MANDATORY)

This creator skill is part of a coordinated creator ecosystem. Any artifact created here must align with and validate against related creators:

• agent-creator for ownership and execution paths
• skill-creator for capability packaging and assignment
• tool-creator for executable automation surfaces
• hook-creator for enforcement and guardrails
• rule-creator and semgrep-rule-creator for policy and static checks
• template-creator for standardized scaffolds
• workflow-creator for orchestration and phase gating
• command-creator for user/operator command UX

Cross-Creator Handshake (Required)

Before completion, verify all relevant handshakes:

1. Artifact route exists in .claude/CLAUDE.md and related routing docs.
2. Discovery/registry entries are updated (catalog/index/registry as applicable).
3. Companion artifacts are created or explicitly waived with reason.
4. validate-integration.cjs passes for the created artifact.
5. Skill index is regenerated when skill metadata changes.

Research Gate (Exa + arXiv — BOTH MANDATORY)

For new patterns, templates, or workflows, research is mandatory:

1. Use Exa for implementation and ecosystem patterns:
   • mcp__Exa__web_search_exa({ query: '<topic> 2025 best practices' })
   • mcp__Exa__get_code_context_exa({ query: '<topic> implementation examples' })
2. Search arXiv for academic research (mandatory for AI/ML, agents, evaluation, orchestration, memory/RAG, security):
   • Via Exa: mcp__Exa__web_search_exa({ query: 'site:arxiv.org <topic> 2024 2025' })
   • Direct API: WebFetch({ url: 'https://arxiv.org/search/?query=<topic>&searchtype=all&start=0' })
3. Record decisions, constraints, and non-goals in artifact references/docs.
4. Keep updates minimal and avoid overengineering.

arXiv is mandatory (not fallback) when topic involves: AI agents, LLM evaluation, orchestration, memory/RAG, security, static analysis, or any emerging methodology.

Regression-Safe Delivery

• Follow strict RED -> GREEN -> REFACTOR for behavior changes.
• Run targeted tests for changed modules.
• Run lint/format on changed files.
• Keep commits scoped by concern (logic/docs/generated artifacts).

Optional: Evaluation Quality Gate

Run the shared evaluation framework to verify tool quality:

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

Grader assertions for tool artifacts:

• --help response: Tool responds to --help (or -h) with a usage summary including required/optional arguments and at least one example invocation
• shell: false for child processes: Any child_process.spawn or execFile call uses shell: false with array arguments (never shell: true per SE-security rules)
• Graceful missing input handling: Tool exits with a non-zero code and a human-readable error message when required arguments are absent; no unhandled exceptions or crash dumps
• Catalog entry present: Tool is registered in .claude/context/artifacts/catalogs/tool-catalog.md with category, description, and wiring status
• Timeout safety: Long-running operations have explicit timeouts; no infinite loops on missing input

See .claude/skills/skill-creator/EVAL_WORKFLOW.md for full evaluation protocol and grader/analyzer agent usage.