craftbag

Discover, list, load, and explain Agent Skills (SKILL.md) for CLI and MCP hosts.

What it does

craftbag walks project and home skill trees (.agents, plus optional vendor trees for Claude, Cursor, Grok, and Bline). It then:

catalogs skills (list)
prints one skill body (load)
explains why a skill would activate (why)
checks a package (validate)

The same operations exist over MCP stdio (skills_list, skills_load, skills_why, skills_validate). Hosts can filter, rank, and load skills without taking a dependency on any one agent product.

Install

macOS and Linux (Homebrew):

brew install craftbag/tap/craftbag

Windows (Scoop):

scoop bucket add craftbag https://github.com/craftbag/scoop-bucket
scoop install craftbag/craftbag

Both commands install craftbag and craftbag-mcp. The MCP host then runs craftbag-mcp (on macOS GUI apps, use the full path if PATH is empty: /opt/homebrew/bin/craftbag-mcp).

From a Rust toolchain (crates.io):

cargo install --locked craftbag-cli
cargo install --locked craftbag-mcp

Library dependency:

craftbag = "0.1"

From git (unreleased tip):

cargo install --locked --git https://github.com/craftbag/craftbag craftbag-cli
cargo install --locked --git https://github.com/craftbag/craftbag craftbag-mcp

MSRV is 1.85.

Getting started

After cargo install --locked craftbag-cli, run it from a project that already has skills under .agents/skills:

craftbag list --catalog
craftbag load review-pr
craftbag why review-pr --context review
craftbag validate ./path/to/my-skill

This clone has a small tree you can run without picking up your real home skills (same catalog as the demo GIF):

git clone https://github.com/craftbag/craftbag
cd craftbag
cargo build -p craftbag-cli --locked
./target/debug/craftbag list --no-implicit-roots --path demo/workspace/.agents/skills --catalog
./target/debug/craftbag load review-pr --no-implicit-roots --path demo/workspace/.agents/skills
./target/debug/craftbag validate demo/workspace/.agents/skills/review-pr

Claude, Cursor, Grok, or Bline trees are opt-in:

craftbag list --vendor claude --catalog

Demo

craftbag catalog and load

MCP

craftbag-mcp speaks JSON-RPC on stdio. Tools: skills_list, skills_load, skills_why, skills_validate. After brew install or scoop install, craftbag-mcp --help names them.

Claude Desktop (claude_desktop_config.json) and other hosts that take a stdio command:

{
  "mcpServers": {
    "craftbag": {
      "command": "craftbag-mcp",
      "args": ["--vendor", "claude"]
    }
  }
}

Launch --path, --vendor, --user-dir, and --no-implicit-roots are the walk when a tool call omits that field. The host cwd is still the implicit walk root unless you pass --no-implicit-roots.

Library

use craftbag::{discover, DiscoveryOptions};

let cwd = std::env::current_dir()?;
let report = discover(&cwd, &DiscoveryOptions::default())?;
for skill in &report.skills {
    println!("{} {}", skill.name, skill.description);
}

implicit_roots is on by default (cwd-to-git .agents and $HOME/.agents). Set it to false and put collection roots in paths for leftover-only hosts.

Contributing

See CONTRIBUTING.md. Security reports go to SECURITY.md. Roadmap and governance are in ROADMAP.md and GOVERNANCE.md.

License

Apache-2.0 or MIT. You may choose either. See LICENSE and LICENSE-APACHE.

craftbag 0.1.2