["Tools are CLI-executable scripts (.cjs or .mjs)","Keep tools focused (single responsibility)","Add help text and usage examples","Include error handling"]
error_handling
graceful
streaming
supported
output_location
.claude/tools/
verified
true
lastVerifiedAt
2026-02-28
dependencies
["research-synthesis"]
source
builtin
trust_score
100
provenance_sha
ae79e0adf62bacae
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:
hook-creator - Create pre/post hooks that wrap tool execution
Iron Laws
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.
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.
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.
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.
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
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' })
Record decisions, constraints, and non-goals in artifact references/docs.
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:
--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.
