skillpack 0.4.0

Generate and verify the agent-distribution layer (Claude Code skill packs) for any OSS project.
Documentation

skillpack

Turn any OSS library or CLI into an agent-discoverable skill pack for Claude Code, Cursor, and Codex.

CI crates.io License: MIT Rust 1.74+

Coding agents (Claude Code, Cursor, Codex) now discover and invoke tools by reading marketplace manifests, skill files, and CLIs — not by npm install-ing on instinct. An OSS project's code quality no longer matters if the agent can't find, understand, and autonomously invoke the tool. That wiring around a library or CLI is the distribution layer, and skillpack generates it for you — then verifies that a coding agent coming in cold could actually use what you shipped.

skillpack takes any OSS project and generates the agent distribution files for one or more coding-agent ecosystems (Claude Code, Cursor, Codex), then runs a verification suite that simulates an agent's first read and actually invokes the documented CLI to catch drift before it reaches a user.

What it generates

From your repo, skillpack init writes (purely additive — nothing existing is touched). By default it targets Claude Code; pass --target cursor / --target codex to emit for additional agents (repeatable):

Claude Code (--target claude, default):

  • .claude-plugin/marketplace.json — a single-plugin marketplace entry pointing at your project root
  • .claude-plugin/plugin.json — the plugin manifest (name, version, author, repo URL)
  • skills/<tool-name>/SKILL.md — the operational knowledge file an agent reads (frontmatter + body, including a ### Subcommands block for CLIs with subcommands)

Cursor (--target cursor):

  • .cursor/rules/<tool-name>.mdc — a Cursor project rule with description / alwaysApply frontmatter and the same invocation body

Codex CLI (--target codex):

  • .codex/skills/<tool-name>/SKILL.md — same SKILL.md frontmatter and body as Claude (cross-agent compatible), installed under Codex's .codex/skills/ convention

A skillpack.toml at your project root captures your answers so re-runs are deterministic and CI-friendly.

Supported ecosystems

Language CLI detection
Rust built binary under target/, or on PATH
Node node <script> from a package.json bin
Python python -m <pkg> from [project.scripts]
Go go run . for a package main project
Ruby a ruby exe/<name> (or bin/<name>) binstub

Projects without a CLI take the pure-library path: SKILL.md documents the install + import pattern instead, and the invocation test is a no-op. The has_cli flag is the single branching point.

Platform: V1 targets Unix (Linux/macOS). CLI detection probes PATH without PATHEXT, so on Windows a bare node lookup misses node.exe and verify will honestly report has_cli=false and skip the invocation check rather than crash. Run on WSL/Linux/CI, or contribute PATHEXT enumeration.

Install

cargo install skillpack    # from crates.io

Or build from source: cargo install --path . (or cargo build --release for a local binary under target/release/).

Requires Rust 1.74+. Published on crates.io.

Quick start

# In your OSS project root:
skillpack init            # introspect → interview → generate → pre-commit verify

# Generate for multiple agent ecosystems at once:
skillpack init --target claude --target cursor --target codex

# Re-run anywhere / in CI (deterministic, non-interactive):
skillpack init --non-interactive --accept-warnings

# Check a generated (or hand-written) skill pack:
skillpack verify

init runs the full verify suite against its own output before writing files, so the worst case — a broken skill pack that looks fine until an agent tries to use it — is caught up front.

What verify checks

Discovery — structural validation per ecosystem. Claude Code (the .claude-plugin/ + skills/ set) is checked against the documented plugin schema:

  • plugin / marketplace names are kebab-case and not reserved
  • description is present and the combined description + when_to_use stays under the 1,536-character listing cap
  • when_to_use carries trigger phrases an agent can match on
  • marketplace source paths use the ./ prefix and forward slashes only
  • version is present in plugin.json (warns on missing/empty)
  • author is present in plugin.json (warns on missing or "Unspecified")

Cursor (.cursor/rules/<name>.mdc) — frontmatter is parsed and validated against cursor.com/docs/rules: description present, non-empty, under the 1,536-char listing cap; alwaysApply present and boolean (missing or non-boolean warns). Codex (.codex/skills/<name>/SKILL.md) reuses the same SKILL.md frontmatter schema as Claude (fields, length caps, name validation), namespaced under discovery.codex.skill.*. A --target cursor-only pack (legitimately without .claude-plugin/) passes verify without a false-positive Claude-side failure.

Invocation — actually runs the documented CLI:

  • --help executes cleanly under a hard timeout
  • every flag documented in SKILL.md exists in the real --help output (catches drift)
  • flags the CLI advertises in --help that SKILL.md doesn't document (a discoverability warning, so an agent doesn't miss options)
  • for CLIs with subcommands (clap-style Commands: sections), init captures each subcommand's --help and documents them in a ### Subcommands block; verify spawns <cli> <sub> --help per documented subcommand and drift-checks its flags

verify works on hand-written skill packs too, not just init output: it derives whether a CLI is documented from the SKILL.md itself (a ## Invocation section, or a fenced block with --flags). If the skill documents a CLI but no runnable binary is found on your machine, the invocation check is reported as a warning (not silently skipped), so the gap is visible. The invocation check runs against the first documented CLI; discovery checks above run against every SKILL.md (a plugin may ship several).

Exits non-zero on any critical failure, so it drops straight into CI as a PR gate. Pass --format json for a machine-readable report (per-check ids, counts, ok flag) for scripting.

Flags

Flag Purpose
init --non-interactive skip prompts; requires a skillpack.toml (for CI)
init --accept-warnings write files even when verify flags warnings (critical still blocks). Without it, warnings prompt before writing in interactive mode
init --license <SPDX> override the license for this run
init --target <ecosystem> agent ecosystem(s) to generate for: claude (default), cursor, codex. Repeatable.
verify --format human|json human report (default) or machine-readable JSON for CI
--verbose print what skillpack detected in the repo (introspection)
--debug print every subprocess call

Status

init + verify across the five language ecosystems above. Generates and verifies distribution files for Claude Code (default), Cursor (.cursor/rules/*.mdc), and Codex CLI (.codex/skills/). MIT-licensed. verify runs the discovery suite against every ecosystem init targets — a broken .mdc or Codex SKILL.md fails CI alongside a Claude-side defect. A bundled skill-pack marketplace is a later phase.

Contributing

See CONTRIBUTING.md. Template edits (templates/*.tera) need no Rust knowledge — the snapshot tests catch any silent change to generated output.

License

MIT. See LICENSE. See CHANGELOG.md for release history.