Agent-Skills.md

Agent Skills: Tool Creator

Creates tool files for the Claude Code framework. Tools are executable utilities organized by category in .claude/tools/.

UncategorizedID: oimiragieo/agent-studio/tool-creator

Repository

oimiragieo/agent-studio
oimiragieo
19

Install this agent skill to your local

pnpm dlx add-skill https://github.com/oimiragieo/agent-studio/tree/HEAD/.claude/skills/tool-creator

Skill Files

Browse the full folder contents for tool-creator.

Download Skill

Loading file tree…

.claude/skills/tool-creator/SKILL.md

Skill Metadata

Name
tool-creator
Description
Creates tool files for the Claude Code framework. Tools are executable utilities organized by category in .claude/tools/.

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/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/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.