agent-bootstrap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Bootstrap: Declarative Environment Setup

Agent Bootstrap：声明式环境搭建

You bootstrap the agentic development environment by reading

agent.toml

and configuring the current tool (Claude Code, OpenCode, etc.) accordingly.

你可以通过读取

agent.toml

并据此配置当前工具（Claude Code、OpenCode等），来启动智能体开发环境。

Usage

使用方法

/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-bootstrap           # 验证环境并配置工具
/agent-bootstrap --verify  # 运行所有验证检查
/agent-bootstrap --check   # 试运行：报告将要配置的内容

Core Principle

核心原则

Self-bootstrap without external dependencies. The manifest (

agent.toml

) + this skill = complete environment setup. No

curl|bash

, no package managers, no external tools.

无需外部依赖的自启动。清单文件（agent.toml）+ 本技能 = 完整的环境搭建。无需

curl|bash

、包管理器或外部工具。

Quick Reference

快速参考

Use this skill when:

Starting work in a new repository
Environment feels misconfigured
Checks are failing unexpectedly
Setting up a new machine

What this skill does:

Reads
```
agent.toml
```
from repository root
Validates environment (required vars, commands, runtimes)
Configures plugins for the current tool
Generates MCP server config
Reports status (or runs verification checks with
```
--verify
```
)

在以下场景使用本技能：

开始在新仓库中工作时
环境配置出现问题时
检查意外失败时
配置新机器时

本技能的功能：

从仓库根目录读取
```
agent.toml
```
验证环境（所需变量、命令、运行时）
为当前工具配置插件
生成MCP服务器配置
报告状态（或使用
```
--verify
```
运行验证检查）

The States

状态说明

State AB0: No Manifest

状态AB0：无清单文件

Symptoms:

No
```
agent.toml
```
in repository root
User asks to bootstrap but no manifest exists

Key Questions:

Should we create a starter
```
agent.toml
```
?
What environment requirements does this project have?

Interventions:

Offer to create a minimal
```
agent.toml
```
based on detected project type
Check for common patterns (Cargo.toml → Rust, package.json → Node, etc.)
Link to docs/agent-toml-spec.md if it exists

症状：

仓库根目录下无
```
agent.toml
```
文件
用户要求启动但不存在清单文件

关键问题：

是否需要创建一个初始的
```
agent.toml
```
？
该项目有哪些环境要求？

处理方式：

根据检测到的项目类型，主动提供创建最小化
```
agent.toml
```
的服务
检查常见项目特征（Cargo.toml → Rust，package.json → Node等）
如果存在相关文档，链接至docs/agent-toml-spec.md

State AB1: Manifest Found, Validation Needed

状态AB1：找到清单文件，需验证

Symptoms:

```
agent.toml
```
exists at repository root
Environment not yet validated
User invoked
```
/agent-bootstrap
```

Key Questions:

Are all required environment variables set?
Are all required commands in PATH?
Do runtime versions meet constraints?

Interventions:

Parse
```
agent.toml
```
using TOML parser
Check each
```
required_env
```
variable
Check each
```
required_commands
```
command
Check runtime versions against constraints
Report any failures with actionable guidance

症状：

仓库根目录下存在
```
agent.toml
```
环境尚未验证
用户调用了
```
/agent-bootstrap
```

关键问题：

所有必需的环境变量是否已设置？
所有必需的命令是否在PATH中？
运行时版本是否符合要求？

处理方式：

使用TOML解析器解析
```
agent.toml
```
检查每个
```
required_env
```
变量
检查每个
```
required_commands
```
命令
核对运行时版本是否符合约束
报告所有失败项并提供可操作的解决指引

State AB2: Environment Valid, Configuration Needed

状态AB2：环境验证通过，需配置

Symptoms:

Environment validation passed
Tool configuration not yet applied
Plugins, MCP servers, or hooks need setup

Key Questions:

Which plugins need to be enabled?
What MCP servers should be configured?
Which hooks should be applied?

Interventions:

For Claude Code:
- Update
```
.claude/settings.json
```
  with enabled plugins
- Generate
```
.mcp.json
```
  from MCP server definitions
- Note: Hooks require user to copy to their settings (tool-specific)
Report configuration changes made

症状：

环境验证已通过
工具配置尚未应用
插件、MCP服务器或钩子需要设置

关键问题：

需要启用哪些插件？
应配置哪些MCP服务器？
需要应用哪些钩子？

处理方式：

对于Claude Code：
- 更新
```
.claude/settings.json
```
  以启用插件
- 根据MCP服务器定义生成
```
.mcp.json
```
- 注意：钩子需要用户手动复制到其设置中（工具特定）
报告已完成的配置变更

State AB3: Configured, Verification Mode

状态AB3：已配置，验证模式

Symptoms:

User invoked
```
/agent-bootstrap --verify
```
Need to run verification checks

Key Questions:

Which checks should run (based on trigger)?
Did all checks pass?

Interventions:

Run all

[[verification.checks]]

with

trigger = "stop"

trigger = "explicit"

Report pass/fail status for each
If any fail, report the failure and suggest fixes
Block completion if running as stop hook

症状：

用户调用了
```
/agent-bootstrap --verify
```
需要运行验证检查

关键问题：

应运行哪些检查（基于触发条件）？
所有检查是否通过？

处理方式：

运行所有

[[verification.checks]]

中

trigger = "stop"

或

trigger = "explicit"

的检查项

报告每个检查项的通过/失败状态
若有失败项，报告失败原因并建议修复方案
如果作为停止钩子运行，若有失败则阻止完成

Execution Process

执行流程

Phase 1: Parse Manifest

阶段1：解析清单文件

bash

undefined

bash

undefined

Read agent.toml from repository root

从仓库根目录读取agent.toml


Parse the TOML file and extract:
- `[manifest]` - version check (1.1 for remote skill support)
- `[environment]` - validation requirements
- `[[skills]]` - skill definitions (local and remote)
- `[[plugins.*]]` - plugin configuration
- `[[mcp.servers]]` - MCP server definitions
- `[[hooks.*]]` - hook definitions
- `[[verification.checks]]` - verification checks


解析TOML文件并提取以下内容：
- `[manifest]` - 版本检查（1.1版本支持远程技能）
- `[environment]` - 验证要求
- `[[skills]]` - 技能定义（本地和远程）
- `[[plugins.*]]` - 插件配置
- `[[mcp.servers]]` - MCP服务器定义
- `[[hooks.*]]` - 钩子定义
- `[[verification.checks]]` - 验证检查项

Phase 1.5: Install Remote Skills

阶段1.5：安装远程技能

For each skill with a

source

field (rather than

path

), install from remote:

Source Format Detection:

Pattern	Type	Installation
`owner/repo@skill`	GitHub	`npx skills add owner/repo@skill -g -y`
`owner/repo@skill` + version	GitHub pinned	`npx skills add owner/repo@skill#version -g -y`
`skills.sh/name`	Registry	`npx skills add name -g -y`
`https://.../raw/.../skill`	Raw URL	Fetch SKILL.md directly to ~/.claude/skills/
`https://....git@skill`	Git URL	`npx skills add <url> -g -y`

Installation Process:

Check if skill already installed:
```
ls ~/.claude/skills/skill-name/SKILL.md
```
If not installed, determine source type and run appropriate command
Verify installation succeeded

Report Format:

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 Installation (for Gitea/GitLab):

When source starts with

https://

and contains

/raw/

bash

undefined

对于每个带有

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`

安装流程：

检查技能是否已安装：
```
ls ~/.claude/skills/skill-name/SKILL.md
```
若未安装，判断源类型并运行相应命令
验证安装是否成功

报告格式：

正在安装远程技能...

[1/34] gitea-workflow
  源：jwynia/agent-skills@gitea-workflow
  ✓ 已安装

[2/34] code-review
  源：jwynia/agent-skills@code-review
  ✓ 已安装

[3/34] custom-skill
  源：https://gitea.example.com/.../raw/.../custom-skill
  ✗ 安装失败：连接被拒绝

远程技能：32/34已安装，1个已存在，1个安装失败

原始URL安装（适用于Gitea/GitLab）：

当源以

https://

开头且包含

/raw/

时：

bash

undefined

Create skill directory

创建技能目录

mkdir -p ~/.claude/skills/skill-name

Fetch SKILL.md directly

直接获取SKILL.md

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


**Skills with version field:**

When a skill has both `source` and `version`:
```toml
[[skills]]
name = "code-review"
source = "jwynia/agent-skills@code-review"
version = "v1.2.0"

Append version as git ref:

npx skills add jwynia/agent-skills@code-review#v1.2.0 -g -y

test -f ~/.claude/skills/skill-name/SKILL.md


**带版本字段的技能：**

当技能同时包含`source`和`version`时：
```toml
[[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

Phase 2: Validate Environment

阶段2：验证环境

For each requirement, check and report:

Environment Variables:

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

Commands:

✓ 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/

Runtimes:

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

对每个要求进行检查并报告：

环境变量：

✓ GITHUB_TOKEN已设置
✗ TAVILY_API_KEY未设置
  → 设置该变量以启用网页搜索功能

命令：

✓ git（路径：/usr/bin/git）
✓ cargo（路径：/home/user/.cargo/bin/cargo）
✗ node未在PATH中找到
  → 安装Node.js：https://nodejs.org/

运行时：

✓ rust 1.78.0 >= 1.75.0
✗ python 3.9.7 不满足 >=3.10要求
  → 将Python升级至3.10或更高版本

Phase 3: Configure Tool

阶段3：配置工具

Detect Current Tool:

Look for
```
.claude/
```
→ Claude Code
Look for
```
.opencode/
```
→ OpenCode
Look for
```
.cline/
```
→ Cline
Look for
```
.cursor/
```
→ Cursor

For Claude Code:

Plugins - Update

.claude/settings.json

json

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

MCP Servers - Generate

.mcp.json

json

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

Hooks - Report hook configuration (requires manual setup):

Hooks defined in agent.toml:
- post_tool_use: rustfmt on *.rs files
- stop: verification script

To enable hooks, add to your Claude Code settings.

检测当前工具：

查找
```
.claude/
```
→ Claude Code
查找
```
.opencode/
```
→ OpenCode
查找
```
.cline/
```
→ Cline
查找
```
.cursor/
```
→ Cursor

对于Claude Code：

插件 - 更新

.claude/settings.json

：

json

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

MCP服务器 - 生成

.mcp.json

：

json

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

钩子 - 报告钩子配置（需手动设置）：

agent.toml中定义的钩子：
- post_tool_use：对*.rs文件执行rustfmt
- stop：验证脚本

如需启用钩子，请添加至你的Claude Code设置中。

Phase 4: Report Status

阶段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

delft-core的启动已完成

环境状态：
  ✓ 所有必需命令均已找到（git、cargo、rustfmt、npx）
  ✓ 所有运行时版本均满足要求（rust 1.78.0、node 20.11.0）
  ⚠ 1个可选环境变量未设置（TAVILY_API_KEY）

远程技能：
  ✓ 34个远程技能已安装
  ⚠ 1个技能安装失败（详见上文）

配置状态：
  ✓ 已启用插件：rust-analyzer-lsp
  ✓ 已生成包含1个服务器的.mcp.json
  ⚠ 钩子需手动配置

可用技能：40个（6个本地，34个远程）

后续步骤：
  - 设置TAVILY_API_KEY以增强网页搜索功能
  - 查看agent.toml中的钩子配置
  - 重试失败的远程技能安装：npx skills add <source> -g -y

Phase 5: Verification (--verify mode)

阶段5：验证（--verify模式）

Run each verification check:

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

运行每个验证检查项：

正在运行验证检查...

[1/4] fmt
  命令：cd src && cargo fmt --check
  ✓ 通过（0.8秒）

[2/4] build
  命令：cd src && cargo build
  ✓ 通过（12.3秒）

[3/4] clippy
  命令：cd src && cargo clippy --workspace -- -D warnings
  ✗ 失败（8.2秒）

  错误：未使用的变量`x`
   --> src/crates/delft-cli/src/main.rs:42:9

[4/4] tests
  命令：cd src && cargo test
  ⏭ 跳过（trigger = explicit，使用--verify运行）

验证结果：3项中2项通过，1项失败

Environment Variable Checking

环境变量检查

Check if variable is set (not its value):

bash

undefined

检查变量是否已设置（不检查值）：

bash

undefined

Bash approach

Bash方式

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


For Claude Code, use the Bash tool to check:
```bash
printenv | grep -q "^VAR_NAME=" && echo "set" || echo "not set"

if [ -z "${VAR_NAME+x}" ]; then echo "VAR_NAME未设置" fi


对于Claude Code，使用Bash工具检查：
```bash
printenv | grep -q "^VAR_NAME=" && echo "已设置" || echo "未设置"

Command Checking

命令检查

bash

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

bash

command -v git >/dev/null 2>&1 && echo "已找到" || echo "未找到"

Runtime Version Checking

运行时版本检查

bash

undefined

bash

undefined

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]+)?'

undefined

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

undefined

File Operations

文件操作

Read agent.toml

读取agent.toml

Use the Read tool to read

agent.toml

from repository root.

使用Read工具从仓库根目录读取

agent.toml

。

Update settings.json

更新settings.json

Use the Edit tool to update

.claude/settings.json

with plugin configuration.

使用Edit工具更新

.claude/settings.json

中的插件配置。

Generate .mcp.json

生成.mcp.json

Use the Write tool to create

.mcp.json

with MCP server configuration.

使用Write工具创建包含MCP服务器配置的

.mcp.json

。

Anti-Patterns

反模式

The Assumption Trap

假设陷阱

Pattern: Assuming environment is correct without validation. Problem: Leads to confusing errors later. Fix: Always validate. Report clearly what's missing.

模式： 未验证就假设环境配置正确。 问题： 后续会导致难以理解的错误。 修复方案： 始终进行验证，清晰报告缺失项。

The Secret Leak

密钥泄露

Pattern: Writing environment variable values to files. Problem: Secrets in version control. Fix: Only write

${VAR_NAME}

references, never values.

模式： 将环境变量值写入文件。 问题： 密钥会被纳入版本控制。 修复方案： 仅写入

${VAR_NAME}

引用，绝不写入实际值。

The Implicit Bootstrap

隐式启动

Pattern: Auto-running bootstrap without user consent. Problem: Security risk; unexpected changes. Fix: Always require explicit

/agent-bootstrap

invocation.

模式： 未经用户同意自动运行启动流程。 问题： 存在安全风险，会产生意外变更。 修复方案： 始终要求用户显式调用

/agent-bootstrap

。

The Over-Configuration

过度配置

Pattern: Configuring everything even when not needed. Problem: Confusing state; hard to debug. Fix: Only configure what's declared in manifest.

模式： 即使不需要也配置所有内容。 问题： 状态混乱，难以调试。 修复方案： 仅配置清单文件中声明的内容。

Example Interactions

示例交互

Example 1: Fresh Start

示例1：全新开始

User:

/agent-bootstrap

Your approach:

Read
```
agent.toml
```
from repository root
Validate environment requirements
Configure Claude Code settings
Generate MCP config if servers defined
Report status and next steps

用户：

/agent-bootstrap

处理流程：

从仓库根目录读取
```
agent.toml
```
验证环境要求
配置Claude Code设置
若定义了服务器则生成MCP配置
报告状态及后续步骤

Example 2: Verification

示例2：验证

User:

/agent-bootstrap --verify

Your approach:

Read verification checks from
```
agent.toml
```
Run each check with
```
trigger = "stop"
```
or
```
trigger = "explicit"
```
Report pass/fail for each
Summarize results

用户：

/agent-bootstrap --verify

处理流程：

从
```
agent.toml
```
读取验证检查项
运行所有
```
trigger = "stop"
```
或
```
trigger = "explicit"
```
的检查项
报告每个检查项的通过/失败状态
汇总结果

Example 3: Check Mode

示例3：检查模式

User:

/agent-bootstrap --check

Your approach:

Parse
```
agent.toml
```
Report what would be validated and configured
Do not make any changes
List any issues found

用户：

/agent-bootstrap --check

处理流程：

解析
```
agent.toml
```
报告将要验证和配置的内容
不进行任何实际变更
列出发现的所有问题

Example 4: No Manifest

示例4：无清单文件

User:

/agent-bootstrap

(no agent.toml exists)

Your approach:

Report that no manifest found
Offer to create a starter manifest based on project detection
If user agrees, create minimal
```
agent.toml
```
Link to specification documentation

用户：

/agent-bootstrap

（不存在agent.toml）

处理流程：

报告未找到清单文件
根据项目检测结果，主动提供创建初始清单文件的服务
若用户同意，创建最小化的
```
agent.toml
```
链接至规范文档

Integration Graph

集成关系图

Inbound (From Other Skills)

入站（来自其他技能）

Source Skill	Source State	Leads to State
(none)	-	AB0 or AB1

源技能	源状态	指向状态
（无）	-	AB0或AB1

Outbound (To Other Skills)

出站（指向其他技能）

This State	Leads to Skill	Target State
AB2 (configured)	gitea-workflow	(ready to work)
AB3 (verified)	(any)	(environment confirmed)

当前状态	指向技能	目标状态
AB2（已配置）	gitea-workflow	（可工作状态）
AB3（已验证）	（任意）	（环境已确认）

Complementary Skills

互补技能

Skill	Relationship
find-skills	Discover skills listed in manifest
context-network	May be bootstrapped after environment setup

技能	关系
find-skills	发现清单文件中列出的技能
context-network	可在环境搭建完成后启动

Manifest Schema Reference

清单文件架构参考

See

docs/agent-toml-spec.md

for the complete schema specification.

Key sections:

```
[manifest]
```
- version (1.1 for remote skill support)
```
[environment]
```
- required_env, required_commands, runtimes
```
[[skills]]
```
- skill definitions (local with
```
path
```
, remote with
```
source
```
)
```
[[plugins.{tool}]]
```
- plugin configuration
```
[[mcp.servers]]
```
- MCP server definitions
```
[[hooks.{tool}]]
```
- hook configuration
```
[[verification.checks]]
```
- verification checks

完整架构规范请查看

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]]
```
- 验证检查项

Skills Schema (v1.1)

技能架构（v1.1）

toml

undefined

toml

undefined

Local skill

本地技能

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

Remote skill (GitHub)

远程技能（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"

undefined

[[skills]] name = "gitea-workflow" source = "jwynia/agent-skills@gitea-workflow" version = "v1.0.0"

undefined