agent-bootstrap

エージェントのブートストラップ：宣言的な環境設定

agent.toml を読み込み、現在のツール（Claude Code、OpenCode など）を適切に設定することで、エージェント開発環境をブートストラップします。

使い方

/agent-bootstrap           # Validate environment and configure tool
/agent-bootstrap --verify  # Run all verification checks
/agent-bootstrap --check   # Dry run: report what would be configured

基本原則

外部依存なしでセルフブートストラップします。 マニフェスト（agent.toml）とこのスキルだけで、環境設定が完了します。curl|bash、パッケージマネージャー、外部ツールは不要です。

クイックリファレンス

このスキルは、次の場合に使用します：

• 新しいリポジトリで作業を始めるとき
• 環境の設定に問題があると感じたとき
• チェックが予期せず失敗するとき
• 新しいマシンをセットアップするとき

このスキルで行うこと：

1. リポジトリのルートから agent.toml を読み込む
2. 環境を検証する（必須の変数、コマンド、ランタイム）
3. 現在のツール用にプラグインを設定する
4. MCP サーバー設定を生成する
5. ステータスを報告する（または --verify を指定して検証チェックを実行する）

状態

状態 AB0：マニフェストなし

症状：

• リポジトリのルートに agent.toml がない
• ユーザーがブートストラップを求めているが、マニフェストが存在しない

主な質問：

• 最初の agent.toml を作成しますか？
• このプロジェクトに必要な環境要件は何ですか？

対応：

• 検出したプロジェクトの種類に基づき、最小限の agent.toml の作成を提案する
• 一般的なパターンを確認する（Cargo.toml → Rust、package.json → Node など）
• docs/agent-toml-spec.md が存在する場合は、そのドキュメントへのリンクを案内する

---

状態 AB1：マニフェストを検出、検証が必要

症状：

• リポジトリのルートに agent.toml が存在する
• 環境がまだ検証されていない
• ユーザーが /agent-bootstrap を実行した

主な質問：

• 必須の環境変数はすべて設定されていますか？
• 必須コマンドはすべて PATH にありますか？
• ランタイムのバージョンは制約を満たしていますか？

対応：

• TOML パーサーを使って agent.toml を解析する
• 各 required_env 変数を確認する
• 各 required_commands コマンドを確認する
• ランタイムのバージョンを制約と照合する
• 失敗があれば、実行可能な対処方法とともに報告する

---

状態 AB2：環境は有効、設定が必要

症状：

• 環境の検証に合格した
• ツールの設定がまだ適用されていない
• プラグイン、MCP サーバー、またはフックのセットアップが必要

主な質問：

• どのプラグインを有効にする必要がありますか？
• どの MCP サーバーを設定しますか？
• どのフックを適用しますか？

対応：

• Claude Code の場合：
  • 有効にするプラグインを .claude/settings.json に反映する
  • MCP サーバーの定義から .mcp.json を生成する
  • 注：フックを設定するには、ユーザーが自身の設定にコピーする必要があります（ツール固有）
• 行った設定変更を報告する

---

状態 AB3：設定済み、検証モード

症状：

• ユーザーが /agent-bootstrap --verify を実行した
• 検証チェックを実行する必要がある

主な質問：

• （トリガーに基づき）どのチェックを実行しますか？
• すべてのチェックに合格しましたか？

対応：

• trigger = "stop" または trigger = "explicit" のすべての [[verification.checks]] を実行する
• 各チェックの合格／失敗状況を報告する
• 失敗があれば、失敗内容を報告し、修正方法を提案する
• stop hook として実行中の場合、完了をブロックする

---

実行プロセス

フェーズ 1：マニフェストの解析

# Read agent.toml from repository root

TOML ファイルを解析し、以下を抽出します：

• [manifest] - バージョンの確認（リモートスキルのサポートには 1.1）
• [environment] - 検証要件
• [[skills]] - スキルの定義（ローカルおよびリモート）
• [[plugins.*]] - プラグインの設定
• [[mcp.servers]] - MCP サーバーの定義
• [[hooks.*]] - フックの定義
• [[verification.checks]] - 検証チェック

フェーズ 1.5：リモートスキルをインストールする

path ではなく source フィールドを持つ各スキルについて、リモートからインストールします。

ソース形式の判定：

パターン	種類	インストール
owner/repo@skill	GitHub	npx skills add owner/repo@skill -g -y
owner/repo@skill + バージョン	GitHub 固定	npx skills add owner/repo@skill#version -g -y
skills.sh/name	レジストリ	npx skills add name -g -y
https://.../raw/.../skill	Raw URL	SKILL.md を直接 ~/.claude/skills/ に取得
https://....git@skill	Git URL	npx skills add <url> -g -y

インストール手順：

1. スキルがすでにインストールされているか確認します：ls ~/.claude/skills/skill-name/SKILL.md
2. インストールされていない場合は、ソースの種類を判定し、適切なコマンドを実行します
3. インストールが成功したことを確認します

報告形式：

Installing remote skills...

[1/34] gitea-workflow
  Source: jwynia/agent-skills@gitea-workflow
  ✓ Installed

[2/34] code-review
  Source: jwynia/agent-skills@code-review
  ✓ Already installed

[3/34] custom-skill
  Source: https://gitea.example.com/.../raw/.../custom-skill
  ✗ Failed: Connection refused

Remote skills: 32/34 installed, 1 already present, 1 failed

Raw URL のインストール（Gitea/GitLab 向け）：

ソースが https:// で始まり、/raw/ を含む場合：

# Create skill directory
mkdir -p ~/.claude/skills/skill-name

# Fetch SKILL.md directly
curl -sSL "https://gitea.example.com/.../raw/.../skill-name/SKILL.md" \
  -o ~/.claude/skills/skill-name/SKILL.md

# Verify file was created
test -f ~/.claude/skills/skill-name/SKILL.md

version フィールドを持つスキル：

スキルに source と version の両方がある場合：

[[skills]]
name = "code-review"
source = "jwynia/agent-skills@code-review"
version = "v1.2.0"

バージョンを Git の参照として追加します：npx skills add jwynia/agent-skills@code-review#v1.2.0 -g -y

フェーズ 2：環境を検証する

各要件を確認し、結果を報告します。

環境変数：

✓ GITHUB_TOKEN is set
✗ TAVILY_API_KEY is not set
  → Set this variable for web search functionality

コマンド：

✓ git (found at /usr/bin/git)
✓ cargo (found at /home/user/.cargo/bin/cargo)
✗ node not found in PATH
  → Install Node.js: https://nodejs.org/

ランタイム：

✓ rust 1.78.0 >= 1.75.0
✗ python 3.9.7 does not satisfy >=3.10
  → Upgrade Python to 3.10 or later

フェーズ 3：ツールを設定する

現在のツールを検出する：

• .claude/ を探す → Claude Code
• .opencode/ を探す → OpenCode
• .cline/ を探す → Cline
• .cursor/ を探す → Cursor

Claude Code の場合：

1. プラグイン - .claude/settings.json を更新します：

   {
     "enabledPlugins": {
       "plugin-name@marketplace": true
     }
   }
   

2. MCP サーバー - .mcp.json を生成します：

   {
     "server-name": {
       "type": "http",
       "url": "https://...",
       "headers": {
         "Authorization": "Bearer ${ENV_VAR}"
       }
     }
   }
   

3. フック - フックの設定について報告します（手動設定が必要です）：

   Hooks defined in agent.toml:
   - post_tool_use: rustfmt on *.rs files
   - stop: verification script
   
   To enable hooks, add to your Claude Code settings.
   

フェーズ 4：状況を報告する

Bootstrap complete for delft-core

Environment:
  ✓ All required commands found (git, cargo, rustfmt, npx)
  ✓ All runtime versions satisfied (rust 1.78.0, node 20.11.0)
  ⚠ 1 optional env var not set (TAVILY_API_KEY)

Remote Skills:
  ✓ 34 remote skills installed
  ⚠ 1 skill failed to install (see above)

Configuration:
  ✓ Enabled plugin: rust-analyzer-lsp
  ✓ Generated .mcp.json with 1 server
  ⚠ Hooks require manual configuration

Skills: 40 skills available (6 local, 34 remote)

Next steps:
  - Set TAVILY_API_KEY for enhanced web search
  - Review hooks configuration in agent.toml
  - Retry failed remote skill installs: npx skills add <source> -g -y

フェーズ 5：検証（--verify モード）

各検証チェックを実行します。

Running verification checks...

[1/4] fmt
  Command: cd src && cargo fmt --check
  ✓ PASSED (0.8s)

[2/4] build
  Command: cd src && cargo build
  ✓ PASSED (12.3s)

[3/4] clippy
  Command: cd src && cargo clippy --workspace -- -D warnings
  ✗ FAILED (8.2s)

  error: unused variable `x`
   --> src/crates/delft-cli/src/main.rs:42:9

[4/4] tests
  Command: cd src && cargo test
  ⏭ SKIPPED (trigger = explicit, use --verify to run)

Verification: 2/3 passed, 1 failed

環境変数の確認

変数が設定されているかを確認します（値は確認しません）。

# Bash approach
if [ -z "${VAR_NAME+x}" ]; then
  echo "VAR_NAME is not set"
fi

Claude Code の場合、Bash ツールを使って確認します：

printenv | grep -q "^VAR_NAME=" && echo "set" || echo "not set"

コマンドの確認

command -v git >/dev/null 2>&1 && echo "found" || echo "not found"

ランタイムのバージョン確認

# Rust
rustc --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'

# Node
node --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'

# Python
python3 --version | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?'

ファイル操作

agent.toml を読み取る

Read ツールを使って、リポジトリのルートにある agent.toml を読み取ります。

settings.json を更新する

Edit ツールを使って、プラグイン設定を .claude/settings.json に反映します。

.mcp.json を生成する

Write ツールを使って、MCP サーバー設定を含む .mcp.json を作成します。

アンチパターン

思い込みの罠

パターン： 検証せずに環境が正しいと決めつける。 問題： 後で分かりにくいエラーにつながります。 対処法： 必ず検証します。不足しているものを明確に報告します。

シークレットの漏えい

パターン： 環境変数の値をファイルに書き込む。 問題： シークレットがバージョン管理に含まれます。 対処法： ${VAR_NAME} の参照のみを書き込み、値は決して書き込みません。

暗黙のブートストラップ

パターン： ユーザーの同意なしにブートストラップを自動実行する。 問題： セキュリティ上のリスクがあり、予期しない変更が発生します。 対処法： 必ず /agent-bootstrap の明示的な実行を求めます。

過剰な設定

パターン： 必要ない場合でも、すべてを設定する。 問題： 状態が分かりにくくなり、デバッグが困難になります。 対処法： マニフェストで宣言されているものだけを設定します。

やり取りの例

例 1：新規セットアップ

ユーザー： /agent-bootstrap

対応方法：

1. リポジトリのルートにある agent.toml を読み取ります
2. 環境要件を検証します
3. Claude Code の設定を行います
4. サーバーが定義されている場合は、MCP 設定を生成します
5. 状況と次の手順を報告します

---

例 2：検証

ユーザー： /agent-bootstrap --verify

対応方法：

1. agent.toml から検証チェックを読み取ります
2. trigger = "stop" または trigger = "explicit" の各チェックを実行します
3. 各チェックの合格／不合格を報告します
4. 結果を要約します

---

例 3：チェックモード

ユーザー： /agent-bootstrap --check

対応方法：

1. agent.toml を解析します
2. 検証および設定の対象を報告します
3. 変更は行いません
4. 見つかった問題を列挙します

---

例 4：マニフェストがない場合

ユーザー： /agent-bootstrap（agent.toml が存在しない）

対応方法：

1. マニフェストが見つからなかったことを報告します
2. プロジェクトの検出結果に基づき、スターターマニフェストの作成を提案します
3. ユーザーが同意した場合、最小限の agent.toml を作成します
4. 仕様ドキュメントへのリンクを提示します

統合グラフ

インバウンド（他のスキルから）

送信元スキル	送信元の状態	遷移先の状態
（なし）	-	AB0 または AB1

アウトバウンド（他のスキルへ）

この状態	遷移先のスキル	遷移先の状態
AB2（設定済み）	gitea-workflow	（作業可能）
AB3（検証済み）	（任意）	（環境確認済み）

関連スキル

スキル	関係
find-skills	マニフェストに記載されたスキルを検出します
context-network	環境設定後にブートストラップする場合があります

マニフェストのスキーマリファレンス

完全なスキーマ仕様については、docs/agent-toml-spec.md を参照してください。

主なセクション：

• [manifest] - バージョン（リモートスキル対応は 1.1）
• [environment] - required_env、required_commands、runtimes
• [[skills]] - スキル定義（ローカルは path、リモートは source）
• [[plugins.{tool}]] - プラグイン設定
• [[mcp.servers]] - MCP サーバー定義
• [[hooks.{tool}]] - フック設定
• [[verification.checks]] - 検証チェック

スキーマのスキル（v1.1）

# Local skill
[[skills]]
name = "delft-authoring"
path = ".claude/skills/delft-authoring"

# Remote skill (GitHub)
[[skills]]
name = "code-review"
source = "jwynia/agent-skills@code-review"

# Remote skill with version pin
[[skills]]
name = "gitea-workflow"
source = "jwynia/agent-skills@gitea-workflow"
version = "v1.0.0"