Craftbag

What craftbag does

The craftbag MCP server gives CLI and MCP hosts a way to discover and inspect Agent Skills stored as SKILL.md files. It searches project and home skill locations, including .agents trees and optional vendor directories for Claude, Cursor, Grok, and Bline.

Its catalog can identify available skills and expose their names and descriptions. A skill can be retrieved as a complete body, represented as a heading outline, or narrowed to one named section. The server can also explain why a skill would apply to a supplied context and check whether a skill package is valid.

The craftbag MCP server is useful when an agent host needs to choose relevant skills dynamically, inspect their instructions before loading them, or verify a skill directory during development.

How it works

The MCP executable communicates over standard input and output using JSON-RPC. MCP hosts call four tools: skills_list, skills_load, skills_why, and skills_validate. The tool operations correspond to the CLI commands list, load, why, and validate.

By default, discovery uses implicit roots based on the current working directory up to the Git root and the user home directory. These roots look for .agents and supported vendor trees. Tool calls can use launch-time defaults for paths, vendor selection, the user directory, and implicit-root behavior. A call can also provide relevant path or loading options, including an outline or a specific section for skills_load.

Setup and configuration

Install the command-line and MCP binaries with Homebrew on macOS or Linux, Scoop on Windows, or Cargo from crates.io or the Git repository. Package installation provides craftbag and craftbag-mcp; the MCP host runs the latter.

A stdio host configuration points its command at craftbag-mcp. For macOS GUI applications, the full Homebrew path may be needed when the application does not inherit PATH. Launch options include --path, --vendor, --user-dir, and --no-implicit-roots.

For a controlled search, disable implicit roots and provide collection paths explicitly. Vendor trees are opt-in rather than searched automatically. The project also provides a Rust library with discovery options for applications that need library-level access instead of MCP.

Tools and capabilities

• skills_list catalogs discovered skills and supports filtering or catalog-style output.
• skills_load returns a full skill, its heading outline, or one selected section.
• skills_why explains why a skill would activate for a given context.
• skills_validate checks a skill package at a specified path.

The equivalent CLI commands are list, load, why, and validate. The CLI and MCP interfaces use the same underlying discovery behavior, so a workflow can be tested from the command line before being configured in an MCP host.

Limitations and notes

The server reads skills from filesystem paths; the provided material does not describe remote skill registries or network-based discovery. Vendor-specific directories must be enabled explicitly. If no implicit or configured roots contain skills, listing completes successfully and reports that none were found.

The MCP transport described by the project is stdio, not HTTP. The documented minimum supported Rust version is 1.85 when building from source. The project is licensed under either Apache-2.0 or MIT, at the user's choice.