skill-cli

CLI for managing and testing Anthropic Agent Skills (e.g. anthropics/skills).

Install (npm)

# Global
npm install -g ancoder-skill-cli

# Or run without installing
npx ancoder-skill-cli --help

The npm package is self-contained and includes prebuilt binaries for:

• macOS arm64
• macOS x64
• Linux arm64
• Linux x64
• Windows x64

After install, the wrapper selects the correct bundled binary for the current platform automatically.

Build from source (Go)

cd skill-cli
go build -o bin/skill-cli .
# Then run: ./bin/skill-cli --help
# Or via npm: node bin/skill-cli.js --help

Commands

Machine-Readable Skill Layout

Task-oriented skills can now include a deterministic verification harness:

my-skill/
├── SKILL.md
├── skill.contract.yaml
├── evals/
│   └── smoke.yaml
├── fixtures/
└── scripts/

• skill.contract.yaml defines the executable contract: entrypoint, inputs, outputs, invariants, and datasets.
• evals/*.yaml defines runnable verification suites with deterministic checks like file existence, required content, and JSON assertions.
• skill-cli verify materializes fixture data into a temp workspace, runs the skill entrypoint, and enforces the declared checks.

skill-cli verify executes local code declared by the skill contract, so only run it against trusted skills and repositories.

Publish to npm

1. Set repository.url in package.json to your GitHub repo (e.g. git+https://github.com/your-org/skill-cli.git).

2. Build binaries per platform before publishing the npm package:

   bash scripts/build-all.sh

3. Optionally attach the same binaries to a GitHub Release with names:

   • skill-cli-darwin-arm64, skill-cli-darwin-x64
   • skill-cli-linux-x64, skill-cli-linux-arm64
   • skill-cli-win32-x64.exe

4. Publish the package:

   npm login --registry=https://registry.npmjs.org/
   npm publish --access public --registry=https://registry.npmjs.org/ --userconfig ~/.npmrc

Users who npm install -g ancoder-skill-cli get a fully bundled package. No extra binary download is required during install.

Test-Driven Skill Development (100:10:1 Architecture)

skill-cli adopts a test-driven approach to skill development, inspired by oh-my-claudecode's multi-agent orchestration patterns. The core principle: invest the majority of compute in building robust test skills, not the skill itself.

Time Allocation: 100:10:1

When creating a skill for a task, the system simultaneously creates a main skill and a test skill:

Architecture

Phase 1: Test Skill Development (90% compute)
  generate structured acceptance criteria
  -> N planners generate test strategies in parallel
  -> critic reviews + eliminates weak strategies
  -> N executors implement test skills in parallel
  -> golden test evaluation (tournament selection)
  -> repeat until precision threshold met
  -> best test skill selected

Phase 2: Main Skill Development (9% compute)
  generate main skill
  -> test skill verifies (independent executor)
  -> structured diff feedback injected into next prompt
  -> repeat until test skill passes
  -> main skill complete

Phase 3: Final Verification (1% compute)
  end-to-end smoke test

Key Design Principles

1. Separation of Author and Reviewer

The agent that generates the main skill and the agent that runs the test skill operate in separate contexts. This prevents self-approval bias. The verify phase spawns an independent executor to run the test skill, ensuring honest evaluation (borrowed from OMC's verifier lane pattern).

2. Structured Diff Feedback

Test skills output structured diff reports instead of simple pass/fail:

diffs:
  - location: "page 3, paragraph 2"
    type: "content_loss"
    severity: "critical"
    expected: "table with 3 columns and 5 rows"
    actual: "table missing entirely"
  - location: "page 5, heading"
    type: "format_drift"
    severity: "warning"
    expected: "## Second-level heading"
    actual: "### Third-level heading"

This structured feedback is injected back into the main skill's improvement loop, enabling targeted fixes rather than blind retries.

3. QA Cycling with Early Exit

Borrowed from OMC's UltraQA pattern:

• Test skill finds issues -> structured diagnosis -> main skill fixes -> retest -> loop
• Same error appearing 3 times triggers early exit (avoids infinite compute burn)
• Maximum 5 QA cycles per iteration

4. Tournament Selection for Test Skills

During the 90% test skill development phase, multiple test strategies are generated in parallel and evaluated against golden tests (known-correct input/output pairs). The strategy with the highest detection precision wins, similar to OMC's self-improve tournament selection.

5. PRD-Driven Acceptance Criteria

Test skills define concrete, testable acceptance criteria (not vague "implementation is complete"):

Bad:  "PDF conversion works correctly"
Good: "All tables with merged cells are preserved as HTML <table> blocks
       with correct colspan/rowspan attributes"

Example: PDF-to-Markdown Skill

For a PDF-to-Markdown conversion skill:

• Test skill (100 min): Compares original PDF content with generated Markdown, detecting content loss (missing paragraphs, tables, images), format drift (heading levels, list styles), and encoding issues. Outputs structured diffs with page/paragraph-level location info.
• Main skill (10 min): Implements PDF parsing and Markdown generation, iteratively improved by test skill feedback.
• Verification (1 min): End-to-end smoke test on fixture PDFs.

skill_eval Check Type

The verify system supports a skill_eval check type that invokes a test skill as a verification oracle:

checks:
  - id: quality-check
    type: skill_eval
    skill: pdf-to-md-test
    config:
      threshold: 0.95
      output_format: structured_diff

Verify Phase: Independent Executor

During the loop's verify phase, a separate Claude executor is spawned to run the test skill. This executor:

• Has no shared context with the main skill's executor
• Produces an objective evaluation report
• Returns structured diff feedback that feeds into the next iteration

This mirrors OMC's principle: "Keep authoring and review as separate passes."

License

MIT