craftbag

craftbag

发现、列出、加载和说明 CLI 与 MCP 宿主使用的 Agent Skills（SKILL.md）。

功能

craftbag 会遍历项目和主目录中的技能树（.agents，以及可选的 Claude、Cursor、Grok 和 Bline 供应商目录）。然后，它会：

• 为技能编目（list）
• 打印单个技能正文（load），或标题键 / 单个标题（load --outline、load --section KEY）
• 说明技能为何会被激活（why）
• 检查软件包（validate）

同样的操作也可通过 MCP stdio 使用（skills_list、skills_load、skills_why、skills_validate）。宿主可以筛选、排序和加载技能，而无需依赖任何特定的 Agent 产品。

安装

macOS 和 Linux（Homebrew）：

brew install craftbag/tap/craftbag

Windows（Scoop）：

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

这两条命令都会安装 craftbag 和 craftbag-mcp。随后 MCP 宿主会运行 craftbag-mcp（在 macOS 图形界面应用中，如果 PATH 为空，请使用完整路径：/opt/homebrew/bin/craftbag-mcp）。

使用 Rust 工具链安装（crates.io）：

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

库依赖：

craftbag = "0.2"

从 git 安装（未发布的最新版本）：

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

最低支持的 Rust 版本（MSRV）为 1.85。

入门

默认情况下，list 会遍历从当前工作目录到 Git 根目录的 .agents/skills，以及 $HOME/.agents/skills。在传入 --vendor 前，Claude、Cursor、Grok 和 Bline 目录树不会被纳入遍历。如果存在 .cursor/skills（或其他供应商对应的目录），但该供应商未启用，空列表会提示相应标志：hint: .cursor/skills is present; pass --vendor cursor。此克隆没有项目级 .agents 目录。当 .agents 目录不存在时，craftbag list 会以退出码 0 结束，并提示未找到任何技能。craftbag new NAME 会创建 .agents/skills/NAME/SKILL.md，其中包含匹配的名称和占位描述。将 --path 指向演示目录树（与演示 GIF 使用相同的目录）：

git clone https://github.com/craftbag/craftbag
cd craftbag
craftbag list --no-implicit-roots --path demo/workspace/.agents/skills --catalog
craftbag load review-pr --no-implicit-roots --path demo/workspace/.agents/skills
craftbag load review-pr --no-implicit-roots --path demo/workspace/.agents/skills --outline
craftbag load review-pr --no-implicit-roots --path demo/workspace/.agents/skills --section review-a-pull-request
craftbag why review-pr --no-implicit-roots --path demo/workspace/.agents/skills --context review
craftbag validate demo/workspace/.agents/skills/review-pr

--section review-a-pull-request 会传入大纲键。--outline 会在标题 Review a pull request 前打印该键。validate 接收包含 SKILL.md 的软件包目录，此处为 demo/workspace/.agents/skills/review-pr。集合目录 demo/workspace/.agents/skills 本身没有 SKILL.md，因此对它运行 validate 会以退出码 1 结束，并提示 directory is not a skill package (no SKILL.md)。对该目录运行 list --path 仍会列出其中的软件包。

--path、--user-dir 和 --ignore 会自行展开 ~/，因为 MCP 和带引号的命令都没有 shell。~//name 与 ~/name 一样，仍指向你的主目录。如果 ~// 后面的部分仍是 Windows 驱动器路径，则会被拒绝，不会替换你的主目录。路径不存在时会跳过该路径并提示路径不存在。若符号链接的目标已不存在，则会提示符号链接失效。显式指定的 / 和 /.. 是你命名的根目录。经过填充的 .. 若会折叠为 /，例如 /tmp/ ..，则会被拒绝。

如果 craftbag 尚未加入 PATH，请运行 cargo build -p craftbag-cli --locked，并在这些命令中使用 ./target/debug/craftbag。

在 .agents/skills 下已有技能的项目中：

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

Claude、Cursor、Grok 或 Bline 目录树需显式启用：

craftbag list --vendor claude --catalog

演示

MCP

craftbag-mcp 通过标准输入/输出使用 JSON-RPC。工具：skills_list、skills_load、skills_why、skills_validate。prompts/list 和 prompts/get 会将 user_invocable 为 true（默认值）的技能作为 MCP 提示词公开。prompts/get 返回与 load 相同的文本封装。运行 brew install 或 scoop install 后，craftbag-mcp --help 会列出这些工具。带有 "id": null 的请求会以该 id 回复。省略 id 的消息属于通知，不会收到响应。

Claude Desktop（claude_desktop_config.json）及其他接受标准输入/输出命令的宿主：

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

如果工具调用省略了字段，启动参数 --path、--vendor、--user-dir 和 --no-implicit-roots 将用于遍历。除非传入 --no-implicit-roots，否则宿主的当前工作目录仍是隐式遍历根目录。skills_load 接受 outline 和 section（与 load --outline / --section KEY 相同）。

库

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（从当前工作目录到 Git 根目录的 .agents，以及 $HOME/.agents）。对于仅使用剩余目录的宿主，可将其设为 false，并将集合根目录放入 paths。format_load_view 可以打印大纲或单个标题，而不是整个正文。

参与贡献

请参阅 CONTRIBUTING.md。安全问题请报告至 SECURITY.md。路线图和治理信息见 ROADMAP.md 和 GOVERNANCE.md。

许可证

Apache-2.0 或 MIT，任选其一。请参阅 LICENSE 和 LICENSE-APACHE。