craftbag

io.github.craftbagv0.2.1Updated Oct 4, 2026

MCP server to list, load, explain, and validate Agent Skills.

VerifiedSTDIODesktop onlyDeveloper ToolsKnowledge & Memory

Overview

AI-generated overview

Lets an assistant discover, list, load, explain, and validate Agent Skills (SKILL.md) from local skill trees.

What it does
craftbag walks project and home skill trees such as .agents, plus optional vendor trees for Claude, Cursor, Grok, and Bline. Over MCP stdio it exposes skills_list, skills_load, skills_why, and skills_validate. skills_load can return a whole skill body, an outline of heading keys, or a single heading. skills_why explains why a skill would activate, and skills_validate checks a skill package.
When to use it
Useful when a host or agent needs to catalog, inspect, or validate local Agent Skills without depending on one agent product. It fits workflows where skills live in .agents or vendor trees and the assistant must decide which skill applies to a task.
Requirements
A local process on macOS, Linux, or Windows, installed via Homebrew, Scoop, or a Rust toolchain (MSRV 1.85). The MCP host runs craftbag-mcp over stdio; on macOS GUI apps the full path may be needed if PATH is empty. No accounts, API keys, or environment variables are declared.
Before you install
It reads local skill directories, including cwd-to-git .agents and $HOME/.agents by default, and vendor trees only when opted in. Launch flags such as --path, --vendor, --user-dir, and --no-implicit-roots set the walk when a tool call omits that field, so review them to avoid scanning unintended directories.

Installation

In SourceWeft

  1. Open craftbag in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

craftbag

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

[CI] [Security] [crates.io] [docs.rs] [License]

[OpenSSF Best Practices] [OpenSSF Scorecard] [FOSSA Status] [Release]

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), or heading keys / one heading (load --outline, load --section KEY)
  • 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):

bash
brew install craftbag/tap/craftbag

Windows (Scoop):

powershell
scoop bucket add craftbag https://github.com/craftbag/scoop-bucketscoop 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):

bash
cargo install --locked craftbag-clicargo install --locked craftbag-mcp

Library dependency:

toml
craftbag = "0.2"

From git (unreleased tip):

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

MSRV is 1.85.

Getting started

Default list walks cwd-to-git .agents / vendor trees and $HOME/.agents / vendor trees. This clone has no project .agents. When those directories are absent, craftbag list exits 0 and says no skills were found. Point --path at the demo tree (same catalog as the demo GIF):

bash
git clone https://github.com/craftbag/craftbagcd craftbagcraftbag list --no-implicit-roots --path demo/workspace/.agents/skills --catalogcraftbag load review-pr --no-implicit-roots --path demo/workspace/.agents/skillscraftbag load review-pr --no-implicit-roots --path demo/workspace/.agents/skills --outlinecraftbag load review-pr --no-implicit-roots --path demo/workspace/.agents/skills --section review-a-pull-requestcraftbag why review-pr --no-implicit-roots --path demo/workspace/.agents/skills --context reviewcraftbag validate demo/workspace/.agents/skills/review-pr

If craftbag is not on PATH yet, cargo build -p craftbag-cli --locked and use ./target/debug/craftbag in those commands.

In a project that already has skills under .agents/skills:

bash
craftbag list --catalogcraftbag load NAMEcraftbag why NAME --context reviewcraftbag validate ./path/to/my-skill

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

bash
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:

json
{  "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. skills_load accepts outline and section (same as load --outline / --section KEY).

Library

rust
use craftbag::{discover, DiscoveryOptions};
fn main() -> std::io::Result<()> {    let cwd = std::env::current_dir()?;    let report = discover(&cwd, &DiscoveryOptions::default());    for skill in &report.skills {        println!("{} {}", skill.name, skill.description);    }    Ok(())}

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. format_load_view can print an outline or one heading instead of the whole body.

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.

Source: README.md at commit ea02fc9

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.1LatestOct 4, 2026