craftbag

craftbag

CLI および MCP ホスト向けに、エージェントスキル（SKILL.md）を検出、一覧表示、読み込み、説明します。

機能

craftbag は、プロジェクトとホームのスキルツリー（.agents に加え、オプションで Claude、Cursor、Grok、Bline のベンダーツリー）を検索します。次の操作ができます。

• スキルをカタログ化します（list）
• 1 つのスキル本文を出力します（load）。見出しキーや 1 つの見出しを出力することもできます（load --outline、load --section KEY）
• スキルが有効になる理由を説明します（why）
• パッケージを検証します（validate）

同じ操作を MCP stdio 経由でも利用できます（skills_list、skills_load、skills_why、skills_validate）。ホストは特定のエージェント製品に依存せず、スキルをフィルタリング、ランク付け、読み込みできます。

インストール

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 の GUI アプリで 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

MSRV は 1.85 です。

はじめに

デフォルトの list は、cwd から git ルートまでの .agents/skills と $HOME/.agents/skills をたどります。Claude、Cursor、Grok、Bline のツリーは、--vendor を渡すまでこの走査対象に含まれません。.cursor/skills（または別のベンダーに対応するディレクトリ）が存在し、そのベンダーが無効になっている場合、空のリストにはフラグが表示されます：hint: .cursor/skills is present; pass --vendor cursor。このクローンにはプロジェクトの .agents がありません。.agents ディレクトリがない場合、craftbag list は終了コード 0 で終了し、スキルが見つからなかったことを示します。craftbag new NAME は、名前が一致するプレースホルダーの説明を含む .agents/skills/NAME/SKILL.md を作成します。デモ GIF と同じカタログがあるデモツリーを --path に指定します：

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 には、ここでは demo/workspace/.agents/skills/review-pr のように、SKILL.md を含むパッケージディレクトリを指定します。コレクションフォルダー demo/workspace/.agents/skills 自体には SKILL.md がないため、ここに対する validate は終了コード 1 で終了し、directory is not a skill package (no SKILL.md) と表示します。このフォルダーに対する list --path は、引き続き内部のパッケージを一覧表示します。

MCP と引用符で囲んだコマンドにはシェルがないため、--path、--user-dir、--ignore は ~/ をそれぞれ展開します。~//name は ~/name と同様にホームディレクトリの配下になります。~// の残りが Windows のドライブパスである場合は拒否されるため、ホームディレクトリに置き換わることはありません。存在しないパスは読み取り不可としてスキップされ、パスが存在しないことが表示されます。リンク先がなくなっているシンボリックリンクは、dangling symlink と表示されます。明示的に指定した / と /.. は、指定したルートとして扱われます。/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 は stdio 上で 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）および stdio コマンドを受け付けるその他のホスト：

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

ツール呼び出しでフィールドが省略された場合、起動時の --path、--vendor、--user-dir、--no-implicit-roots が走査設定になります。--no-implicit-roots を渡さない限り、ホストの cwd は暗黙の走査ルートになります。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 はデフォルトで有効です（cwd から git ルートまでの .agents と $HOME/.agents）。これを false に設定し、残存分のみを扱うホストではコレクションルートを paths に指定してください。format_load_view は、本文全体の代わりにアウトラインまたは 1 つの見出しを出力できます。

コントリビューション

CONTRIBUTING.md を参照してください。セキュリティに関する報告は SECURITY.md にお寄せください。ロードマップとガバナンスについては、ROADMAP.md と GOVERNANCE.md を参照してください。

ライセンス

Apache-2.0 または MIT。どちらかを選択できます。LICENSE と LICENSE-APACHE を参照してください。