Skillpack

Why skillpack?

AI coding assistants (Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, Freebuff) interact with software differently than humans:

• Humans read high-level READMEs, tutorials, and manual pages to learn syntax.
• AI Agents look for machine-readable skill files, plugin manifests, rule definitions, and structured invocation syntax.

Without an agent guidance layer, AI coding agents frequently:

1. Miss installed tools and attempt to write redundant custom scripts from scratch.
2. Hallucinate invalid CLI flags, resulting in execution failures and broken scripts.
3. Waste context tokens and time repeatedly grepping --help outputs across multiple exploratory reasoning steps.

skillpack solves this with a single command. It introspects your project repository, discovers your CLI binaries or library interfaces, extracts verified argument signatures, and generates tailored distribution files for all major agent ecosystems.

Key Features

• Universal Multi-Ecosystem Generation: Generates native guidance files for 19 agent formats simultaneously (AGENTS.md, Claude Code (plugin + native .claude/skills/), Cursor .mdc, Codex, OpenCode, Copilot, CLAUDE.md, GEMINI.md, Windsurf, Aider, Cline, Roo Code, Kilo Code, Goose, Qoder, Continue, Augment, Amazon Q, and Trae). Freebuff and other AGENTS.md-native agents read the generated AGENTS.md.
• Zero-Drift Verification: Simulates agent invocations against your live CLI to verify that every documented flag and subcommand actually exists.
• Pre-Commit Safe: skillpack init validates the complete surface before writing a single file to disk.
• Non-Destructive Updates: skillpack update refreshes flags and versions while preserving your hand-written descriptions and notes.
• Turnkey CI Integration: Includes GitHub Actions workflows and .pre-commit hooks to prevent documentation drift in pull requests.

Quick Start

1. Installation

# One-command installer (prebuilt binary, no Rust toolchain)
curl -fsSL https://raw.githubusercontent.com/nordicnode/skillpack/main/install.sh | sh

# Or via Homebrew
brew install --formula homebrew/skillpack.rb

# Or via cargo-binstall (prebuilt binary)
cargo install cargo-binstall && cargo binstall skillpack

# Or build from source
cargo install skillpack --locked

2. Scaffold Agent Guidance

Run interactive setup in your project root:

# Interactive setup (asks a few quick questions and persists answers to skillpack.toml)
skillpack init

# Or generate for all supported ecosystems at once:
skillpack init --target all

3. Zero-Interaction Automated Setup (--auto)

For instant, unattended generation in CI or local scripts:

# Introspects README, git config, LICENSE, and compiled CLI binaries automatically
skillpack init --auto --target all

4. Verify Accuracy

Validate your repository's agent guidance against your real CLI:

skillpack verify

What skillpack Generates

Running skillpack init --target all generates a clean, non-intrusive distribution layer:

Measured Benchmark: The skillpack Impact

We benchmarked autonomous coding agents (Google Antigravity agy with Gemini 3.7 Flash) performing complex search and execution tasks on a plain repository clone versus a skillpack-guided clone:

Baseline (Plain Clone):     [Help Grep ×4] ──> [Wandered into other projects] ──> [Success in 60 Rounds] (51s)
Guided (With skillpack):    [Verified Flags, Anchored in Repo] ───────────────────> [Success in 40 Rounds] (35s)

Performance Metrics (Google Antigravity / sharkdp/fd Benchmark Suite, 3 runs per condition)

Full benchmark methodology, repeatable test suites (fd, ripgrep, bat), and replay harness documentation are available in docs/benchmark.md. Want to see it happen? Read the step-by-step docs/agent-demo.md, or reproduce the A/B run yourself from the committed transcripts.

For the emitted file formats per target and what a format change would break, see docs/format-compat.md.

Command-Line Reference

• skillpack init: Scaffold agent distribution files (interactive, --auto, or --non-interactive).
• skillpack verify: Check guidance files against agent schemas and live --help flag surfaces (supports --min-score <N>, --fix, and --format {human,json,sarif,github,junit}).
• skillpack doctor: Diagnose language and CLI candidate discovery decision traces.
• skillpack update: Incrementally regenerate files from skillpack.toml after CLI changes.
• skillpack diff: Preview pending guidance updates without modifying disk.

CI/CD & Pre-Commit Integration

GitHub Actions Workflow

Use the reusable workflow to prevent documentation drift in PRs (it installs a pinned skillpack and runs verify across the OS matrix):

name: Verify Agent Guidance

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  verify:
    uses: nordicnode/skillpack/.github/workflows/[email protected]

For a stricter gate that fails on any warning (not just critical failures), call skillpack verify --min-score 100 directly — that is the bar skillpack holds itself to in its own CI.

Before cutting a release tag, rehearse the release pipeline without publishing: gh workflow run release-rehearsal.yml runs cargo publish --dry-run, the full 6-platform binary build matrix, the version/URL invariants across the Homebrew formula, and a binary smoke test — so a packaging or build problem surfaces before the tag, not after.

Pre-Commit Hook

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/nordicnode/skillpack
    rev: v0.13.2
    hooks:
      - id: skillpack-verify

Supported Language Ecosystems

skillpack automatically detects CLI binaries and library entrypoints across:

• Rust: Built artifacts in target/{release,debug} (including Cargo workspaces) and PATH binaries.
• Node.js: package.json bin fields and ./bin/<name>.js scripts.
• Python: pyproject.toml [project.scripts] and Poetry/Flit entries.
• Go: go run . for package main modules and built binaries.
• Ruby: Gem binstubs in exe/ and bin/.
• PHP: Composer package binaries in vendor/bin.
• JVM: Gradle installDist and Maven shaded JAR entrypoints.
• .NET / C#: SDK-style executable .csproj targets.
• Zig: build.zig / build.zig.zon and artifacts in zig-out/bin/.
• Swift: Package.swift and .build/{debug,release}/ artifacts or swift run.
• C / C++: CMakeLists.txt, meson.build, Makefile and build/ / bin/ binaries.
• Elixir: mix.exs and _build/{dev,prod}/rel/ releases or mix escript.
• Deno: deno.json / deno.jsonc and deno run script entrypoints.
• Nix: flake.nix / shell.nix / default.nix (description capture; flakes are libraries/devshells).
• Dart / Flutter: pubspec.yaml and dart run entrypoints.
• Haskell: *.cabal, cabal.project, stack.yaml and cabal run / stack run.
• Lua: *.rockspec and lua / luajit script entrypoints.
• Julia: Project.toml and julia --project entrypoints.
• Crystal: shard.yml, crystal run, and shards build binaries.
• Clojure: deps.edn / project.clj and lein run / clojure -M.
• OCaml: dune-project / *.opam and dune exec.
• Erlang: rebar.config / *.app.src (name/version detection).
• R: DESCRIPTION / NAMESPACE and Rscript entrypoints.
• Perl: cpanfile / Makefile.PL / META.json and perl script entrypoints.
• Shell / Bash: shebang'd *.sh entrypoints (root, bin/, scripts/, src/) and bash <script> probes.
• PowerShell: .ps1 / .psm1 / .psd1 scripts and pwsh -File probes.

Script-first ecosystems (Shell/PowerShell) are primary-only: a helper .sh or .ps1 inside an otherwise manifest'd repo never mints a secondary skill — only a repo whose main deliverable is scripts gets the Shell/PowerShell category.

Agents that read AGENTS.md natively (Zed, Cody, Kimi CLI, Devin, JetBrains Junie, Freebuff, Warp, Aider) are covered by the agentsmd target — no per-agent file needed.

License & Community

skillpack is open-source software licensed under the MIT License.

• Documentation: See docs/reference.md for full check catalogs and schemas.
• Changelog: See CHANGELOG.md for version release notes.
• Contributing: Contributions are welcome! Review CONTRIBUTING.md to get started.