agent-bootstrap

Agent Bootstrap：声明式环境设置

通过读取 agent.toml 并相应配置当前工具（Claude Code、OpenCode 等），为 Agent 开发环境进行引导设置。

用法

/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
• 需要运行验证检查

关键问题：

• 应运行哪些检查（根据触发条件确定）？
• 所有检查是否都已通过？

处理措施：

• 运行所有 [[verification.checks]] 中 trigger = "stop" 或 trigger = "explicit" 的检查
• 报告每项检查的通过/失败状态
• 如果有任何检查失败，则报告失败情况并建议修复方法
• 如果作为 stop 钩子运行，则阻止完成

---

执行流程

阶段 1：解析清单

# Read agent.toml from repository root

解析 TOML 文件并提取：

• [manifest] - 版本检查（1.1，用于支持远程技能）
• [environment] - 验证要求
• [[skills]] - 技能定义（本地和远程）
• [[plugins.*]] - 插件配置
• [[mcp.servers]] - MCP 服务定义
• [[hooks.*]] - 钩子定义
• [[verification.checks]] - 验证检查

阶段 1.5：安装远程技能

对于每个包含 source 字段（而非 path）的技能，从远程来源安装：

检测来源格式：

模式	类型	安装方式
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	原始 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

原始 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

带版本字段的技能：

当技能同时包含 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"