关于 skill-builder
skill-builder 为 dogfooded-skills 库制定 Agent 技能编写规范，说明文件结构、必备章节及可执行操作手册的写法。
主要功能
- 01技能文件与命名规范
- 02Frontmatter 字段要求
- 03操作手册必备章节
- 04命令与决策表写法
- 05警告、错误及关键规则
适用场景
- 01为该库编写技能
- 02合并前审查技能
- 03将 Agent 指令整理为可执行步骤
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/skill-builder确认已加载。
详细介绍
Skill 构建指南
如何编写一个应纳入此库的 Agent 技能。请严格遵循此标准——dogfooded-skills 中的每项技能在合并前都经过了对照审核。
什么是技能？
技能是位于 .claude/skills/<skill-name>/SKILL.md 的 Markdown 文件。通过调用技能或在项目说明文件中引用技能时，它会加载到 Agent 的上下文中。它不是提示词，而是一份操作手册：包含具体命令、决策表和明确的注意事项，让 Agent 成为某个领域的专家。
技能不是：
- 解释工具用途的 README
- 供用户阅读的示例合集
- 配置文件
- 含糊的注意事项列表
技能是：
- Agent 执行而非阅读的分步说明
- 真实且带有实际标志的命令，而非伪代码
- 某项能力的权威信息源
文件结构
skills/
<skill-name>/
SKILL.md ← required: the skill itself
<support-files> ← optional: scripts, templates, reference data
技能名称使用小写 kebab-case。尽可能简短且不含糊：使用 deps-runner，而非 dependency-update-runner。
-runner 后缀 = 操作员侧的调度器。 名为 *-runner 的技能在开发环境之外运行，并驱动开发环境：它会启动或指定一个工作器，发送提示词、轮询、验证并报告，绝不会在内部直接执行其引擎。其引擎名称不带后缀，且必须能在任何检出目录中运行，无需访问网关。该后缀是 pylot skills list --kind runner 的筛选约定，不得用于其他用途。
Frontmatter
每个 SKILL.md 都必须以 YAML frontmatter 开头：
---
name: skill-name
description: One-line summary — used by the agent to decide relevance. Be specific.
allowed-tools: Read, Write, Bash, Glob, Grep # optional — restrict tool use
---
字段规则
name — 与目录名称一致。不得包含空格或大写字母。
description — 一行简明英文。Agent 会读取此字段，以判断是否调用该技能。错误示例：“管理环境。” 正确示例：“为 CI/Agent 工作负载认领、启动、通过 SSH 连接 Gitpod 云环境，并释放环境。”
requires_worker_skills — 仅适用于 runner：工作器必须具备的引擎技能，使用扁平的内联列表（requires_worker_skills: [ce-debug]；不会读取块状 YAML 列表）。Pylot 会解析每项技能对应的目录来源，并在任务工作器启动时将其安装到用户级作用域；如果无法安装，则启动失败。列出的每个引擎都必须位于组织的技能目录中，并具有 owner/repo 来源。
allowed-tools — 此技能可以使用的工具白名单。省略则允许使用所有工具。若要限制技能的权限（例如只读审计技能），请设置此字段。
章节结构
技能必须按以下顺序包含这些章节：
1. 单行用途说明（H1）
标题就是技能名称。第一段（不带标题）用一句话说明用途。示例：
# deps-runner
Run dependency update PRs through a verification pipeline — checkout, build, test, classify risk, auto-merge or flag.
2. 使用时机（可选，但建议包含）
列出触发条件。Agent 应在什么情况下调用此技能，而不是采取其他做法？
## When to Use
- Dependabot or Renovate PRs that need automated verification
- Batch processing multiple dep updates for the same repo
- When you need a risk classification before merging
3. 先决条件
技能运行前必须满足的所有条件。包含验证命令。
## Prerequisites
```bash
gitpod version && gitpod whoami # Gitpod CLI authenticated
gh auth status # GitHub CLI authenticated
4. 核心工作流
这是技能的核心。使用编号步骤，明确列出实际命令和决策点。
规则：
- 顺序操作使用编号步骤
- 对容易出错的步骤使用
> **Warning:** - 多行 bash 命令使用带
bash语言标记的围栏代码块 - 在有助于验证时展示预期输出
- 决策点使用表格或
if/else说明，不要含糊地写“视情况而定”
示例：
## Workflow
1. **List environments**
```bash
gitpod environment list --timeout 60s
按仓库 URL 筛选。统计此仓库中正在运行或正在停止的环境数量。
-
检查资源池限制 — 如果数量 >= 3（issue）或 >= 2（deps），则中止
-
认领已停止的环境（优先复用而非新建）
gitpod environment start {env-id} --set-as-context --dont-wait认领前检查是否有正在运行的 pilot：
gitpod environment ssh {env-id} -- "pgrep -x claude || echo NO_PILOT"如果存在
claude进程，说明此 pod 已被占用。请选择其他 pod。
### 5. Decision Tables
Use tables whenever there are multiple paths or risk tiers.
```markdown
## Risk Classification
| Condition | Risk | Action |
|-----------|------|--------|
| Patch update, build passes, tests pass | Low | Auto-merge with [skip ci] |
| Minor update, build passes | Medium | Flag for review |
| Major update or build fail | High | Block — manual review required |
6. 错误处理
明确列出失败情况及应对方法。无需面面俱到，只需涵盖不明显的情况。
## Error Handling
**`pgrep -x claude` returns a PID** — pod is mid-mission. Do not claim. Pick a different env.
**Build fails on `bundle install`** — check Ruby version. Lexgo requires Ruby 3.2.x. Run `ruby -v` inside the env.
**`gitpod environment ssh` times out** — env may still be starting. Poll with `gitpod environment get {env-id}` and retry after 15s.
7. 关键规则（可选）
列出绝对必须遵守的规则。如果违反会导致数据丢失、资源泄露或安全问题，请使用此项。
## Critical Rules
- **Always release envs after use** — stopped envs cost nothing; leaked running envs burn credits
- **Never skip decontamination** — a stopped pod resumes with stale git state
- **One agent process per env** — two agents share a git working directory and corrupt each other
描述规则
description: 字段是路由信号——它决定操作人员何时会调用此技能。它必须以可执行的触发条件开头。
| 好的示例 | 不好的示例 |
|---|---|
| “在为仓库运行 deps pipeline 时使用。” | “适用于 deps-runner 的 6 阶段顺序 ICM 流程。” |
| “用于部署到 Fly.io 或配置 flyctl。” | “将应用部署到 Fly.io 平台。” |
| “在处理 Dependabot/Snyk 警报时使用。” | “安全警报处理框架。” |
**自检：**你的描述是否回答了“我应该在什么时候选择此技能？”如果它描述的是技能_如何_工作，而不是_何时_使用，请重写。
可接受的触发形式：“Use when ...”、“Use to ...”、“Use as ...”（仅用于导入的技能）。阶段数、并行性等机制说明应放在技能正文中，而不是描述中。
质量检查清单
提交技能之前，请核实每一项：
- Frontmatter 完整且为有效的 YAML
-
description足够具体，能够与类似技能区分开 - 技能中的每条命令都从真实的终端会话中复制粘贴而来
- 错误处理涵盖最常见的三种故障模式
- 没有伪代码——每个步骤都有真实、可运行的命令
- 决策点使用表格或明确条件，而不是“视情况而定”
- 没有面向用户的指令——所有文字都面向 Agent
- 已针对真实工作负载至少运行此技能 5 次
常见反模式
过于含糊
# Bad
3. Run the appropriate command to start the environment.
# Good
3. Start the environment:
```bash
gitpod environment start {env-id} --set-as-context --dont-wait
### Instructing the user instead of the agent
```markdown
# Bad
The user should verify that the environment is running before proceeding.
# Good
Verify the environment is running:
```bash
gitpod environment get {env-id} --timeout 15s | grep -i "running"
### Missing the "when not to use" case
A skill that can be over-applied is dangerous. If there are situations where the skill should NOT be invoked, say so explicitly.
```markdown
## When NOT to Use
- Major version upgrades with breaking changes — these need manual review
- PRs that touch `schema.rb` or database migrations
将注意事项藏在正文中
注意事项必须在视觉上醒目。使用 > **Warning:**、粗体文本或专门的章节。藏在第三段中的注意事项很容易被忽略。
模板
复制以下内容作为起点：
---
name: your-skill
description: One specific sentence about what this skill does and for what context.
allowed-tools: Read, Write, Bash, Glob, Grep
---
# Your Skill
One sentence: what this skill does and why it exists.
## When to Use
- Trigger A
- Trigger B
## Prerequisites
```bash
# verification commands
工作流
-
步骤一
command here -
步骤二——决策点
条件 操作 情况 A 执行 X 情况 B 执行 Y
错误处理
常见故障——如何处理。
关键规则
- 规则 1
- 规则 2