skillpack 0.12.0

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 10 agent formats simultaneously (AGENTS.md, Claude Code, Cursor .mdc, OpenCode, Copilot, Codex, Windsurf, Freebuff, Gemini, and Aider).
• 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

# Prebuilt binaries — fastest, no Rust toolchain needed
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 performing complex search and execution tasks on a plain repository clone versus a skillpack-guided clone:

Baseline (Plain Clone):     [Tool Error] ──> [Help Grep 1] ──> [Help Grep 2] ──> [Retry 1] ──> [Success in 6 Rounds] (179s)
Guided (With skillpack):    [Direct Execution with Verified Flags] ─────────────> [Success in 1 Round] (82s)

Performance Metrics (OpenCode / sharkdp/fd Benchmark Suite)

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.

🛠️ 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}).
• 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

Add .github/workflows/skillpack.yml to prevent documentation drift in PRs:

name: Verify Agent Guidance

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

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - name: Install skillpack
        run: cargo install skillpack --locked
      - name: Verify Guidance Layer
        run: skillpack verify --min-score 100

Pre-Commit Hook

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

repos:
  - repo: https://github.com/nordicnode/skillpack
    rev: v0.12.0
    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.

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