Agent-Skills.md

Agent Skills: Tool Updater

Research-backed CLI tool refresh workflow for updating existing tools with TDD checkpoints and CLI invocation validation.

UncategorizedID: oimiragieo/agent-studio/tool-updater

Repository

oimiragieo/agent-studio
oimiragieo
416

Install this agent skill to your local

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

Skill Files

Browse the full folder contents for tool-updater.

Download Skill

Loading file tree…

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

Skill Metadata

Name
tool-updater
Description
Research-backed CLI tool refresh workflow for updating existing tools with TDD checkpoints and CLI invocation validation.

Tool Updater

Overview

Use this skill to refresh an existing CLI tool safely: research current best practices, compare against current implementation, generate a TDD patch backlog, apply updates, and verify CLI invocation.

When to Use

  • Tool has broken require() paths or runtime errors
  • Tool's CLI interface needs updating (new flags, changed behavior)
  • Reflection flags stale or low-performing tool
  • User asks to audit/refresh an existing tool

The Iron Law

Never update a tool blindly. Every refresh must be evidence-backed, TDD-gated, and integration-validated.

Workflow

Step 0: Evaluate Current State

  1. Read the tool file and understand its purpose
  2. Check if it's registered in package.json scripts
  3. Test node <tool-path> --help for CLI interface
  4. Identify issues: broken requires, missing error handling, stale logic

Step 1: Research Best Practices

  1. Read .claude/tools/cli/CLAUDE.md for tool conventions
  2. Review similar tools for patterns (especially cli-wrapper.cjs usage)
  3. Check if tool uses wrapCLITool() from ../../lib/utils/cli-wrapper.cjs
  4. Use Skill({ skill: 'research-synthesis' }) if external research needed

Step 2: Generate Patch Backlog

  1. List specific changes needed
  2. Prioritize: broken requires > CLI interface > error handling > logic
  3. Estimate scope: <30 lines = auto-apply, >30 lines = plan mode

Step 3: Apply Updates

  1. Write or update tests first (RED phase)
  2. Apply tool changes (GREEN phase)
  3. Refactor for clarity (REFACTOR phase)
  4. Use Edit tool — never rewrite the entire file

Step 4: Verify Integration

  1. Verify tool loads without MODULE_NOT_FOUND errors
  2. Verify --help output is correct and complete
  3. Verify tool handles missing args gracefully (exit 1 with usage)
  4. If CLI tool, verify package.json script entry exists or add one
  5. Run pnpm lint:fix && pnpm format
  6. Run tool-specific tests

Step 5: Record

  1. Log changes via MemoryRecord if significant
  2. Update CHANGELOG.md entry

Domain-Specific Validation

  • Tool MUST load without MODULE_NOT_FOUND errors
  • Tool MUST handle --help flag and missing arguments gracefully
  • Tool require() paths MUST be file-relative, not CWD-relative
  • Tool MUST use shell: false for any child process spawning (SE security rule)
  • Tool SHOULD use wrapCLITool() for consistent CLI behavior
  • Tool SHOULD be registered in package.json if user-facing

Anti-Patterns

  • Using CWD-relative requires (./.claude/lib/...) instead of file-relative (../../lib/...)
  • Swallowing errors silently in catch blocks
  • Hardcoding paths that should be computed from __dirname
  • Using shell: true in spawn/exec calls