skill-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Builder

Skill 构建指南

How to write an agent skill that belongs in this library. Follow this standard exactly — every skill in

dogfooded-skills

was reviewed against it before merge.

如何编写属于本库的Agent Skill。请严格遵循本标准——

dogfooded-skills

中的每一个Skill在合并前都经过了本标准的审核。

What Is a Skill?

什么是Skill？

A skill is a markdown file at

.claude/skills/<skill-name>/SKILL.md

. It is loaded into the agent's context when invoked via skill invocation or referenced in the project instructions file. It is not a prompt — it is a runbook: concrete commands, decision tables, and explicit gotchas that turn the agent into a domain expert.

A skill is NOT:

A README explaining what a tool does
A collection of examples for the user to read
A configuration file
A vague list of things to consider

A skill IS:

Step-by-step instructions the agent executes, not reads
Real commands with real flags, not pseudocode
The authoritative source of truth for one capability

Skill是位于

.claude/skills/<skill-name>/SKILL.md

的Markdown文件。当通过Skill调用或在项目说明文件中引用时，它会被加载到Agent的上下文环境中。它不是提示词，而是一份执行手册：包含具体命令、决策表和明确的注意事项，使Agent成为领域专家。

Skill 不是：

解释工具功能的README
供用户阅读的示例集合
配置文件
模糊的考虑事项列表

Skill 是：

Agent执行而非阅读的分步指令
带有真实参数的实际命令，而非伪代码
某一项能力的权威事实来源

File Structure

文件结构

skills/
  <skill-name>/
    SKILL.md          ← required: the skill itself
    <support-files>   ← optional: scripts, templates, reference data

Skill names are kebab-case, lowercase. Use the shortest name that's unambiguous:

deps-runner

, not

dependency-update-runner

skills/
  <skill-name>/
    SKILL.md          ← 必填：Skill本体
    <support-files>   ← 可选：脚本、模板、参考数据

Skill名称采用短横线分隔的小写格式（kebab-case）。使用最简短且明确的名称：例如

deps-runner

，而非

dependency-update-runner

。

Frontmatter

Every

SKILL.md

must start with YAML frontmatter:

yaml

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

每个

SKILL.md

必须以YAML Frontmatter开头：

yaml

---
name: skill-name
description: 单行摘要——供Agent判断相关性。请描述具体。
allowed-tools: Read, Write, Bash, Glob, Grep  # 可选——限制工具使用
---

Field rules

字段规则

name
— matches the directory name. No spaces, no uppercase.

description
— one line, plain English. The agent reads this to decide whether to invoke the skill. Bad: "Manage environments." Good: "Claim, start, SSH into, and release Gitpod cloud environments for CI/agent workloads."

allowed-tools
— whitelist of tools this skill may use. Omit to allow all tools. Set when the skill should be restricted (e.g., a read-only audit skill).

name
—— 与目录名称一致。无空格，无大写字母。

description
—— 单行纯英文描述。Agent通过此字段判断是否调用该Skill。反面示例："管理环境。" 正面示例："申领、启动、SSH连接并释放用于CI/Agent工作负载的Gitpod云环境。"

allowed-tools
—— 该Skill可使用的工具白名单。省略则允许所有工具。当Skill需要被限制时设置（例如只读审计Skill）。

Section Structure

章节结构

A skill must have these sections, in order:

Skill必须包含以下章节，按顺序排列：

1. One-line purpose (H1)

1. 单行用途（一级标题）

The title is the skill name. The first paragraph (no heading) is the one-sentence purpose. Example:

markdown

undefined

标题为Skill名称。第一段（无副标题）为单句用途说明。示例：

markdown

undefined

deps-runner

Run dependency update PRs through a verification pipeline — checkout, build, test, classify risk, auto-merge or flag.

undefined

通过验证流水线运行依赖更新PR——检出代码、构建、测试、风险分类、自动合并或标记。

undefined

2. When to Use (optional but recommended)

2. 使用场景（可选但推荐）

Bullet list of triggers. When should the agent invoke this skill vs. doing something else?

markdown

undefined

触发条件的项目符号列表。Agent何时应调用此Skill而非执行其他操作？

markdown

undefined

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

undefined

需要自动验证的Dependabot或Renovate PR
批量处理同一仓库的多个依赖更新
合并前需要风险分类时

undefined

3. Prerequisites

3. 前置条件

Everything that must be true before the skill runs. Include verification commands.

markdown

undefined

Skill运行前必须满足的所有条件。包含验证命令。

markdown

undefined

Prerequisites

前置条件

bash

gitpod version && gitpod whoami  # Gitpod CLI authenticated
gh auth status                    # GitHub CLI authenticated

bash

gitpod version && gitpod whoami  # Gitpod CLI已认证
gh auth status                    # GitHub CLI已认证

undefined

4. Core Workflow

4. 核心工作流

The heart of the skill. Numbered steps, real commands, decision points clearly marked.

Rules:

Use numbered steps for sequential operations
Use
```
> **Warning:**
```
for steps where errors are common
Wrap multi-line bash in fenced code blocks with
```
bash
```
lang
Show expected output when it matters for verification
Decision points use tables or
```
if/else
```
prose, not vague "depending on..."

Example:

markdown

undefined

Skill的核心部分。编号步骤、真实命令、明确标记的决策点。

规则：

顺序操作使用编号步骤
错误高发步骤使用
```
> **Warning:**
```
标记
多行bash命令包裹在带有
```
bash
```
语言标识的围栏代码块中
当验证需要时展示预期输出
决策点使用表格或
```
if/else
```
文字说明，而非模糊的“取决于...”

示例：

markdown

undefined

Workflow

工作流

List environments
bash
```
gitpod environment list --timeout 60s
```
Filter by repository URL. Count running/stopping envs for this repo.
Check pool limits — abort if count >= 3 (issue) or >= 2 (deps)
Claim a stopped env (prefer reuse over create)
bash
```
gitpod environment start {env-id} --set-as-context --dont-wait
```
Check for active pilot before claiming:
bash
```
gitpod environment ssh {env-id} -- "pgrep -x claude || echo NO_PILOT"
```
If a
```
claude
```
process exists, this pod is occupied. Pick another.

undefined

列出环境
bash
```
gitpod environment list --timeout 60s
```
按仓库URL过滤。统计该仓库的运行中/停止中的环境数量。
检查池限制 —— 若数量≥3（问题场景）或≥2（依赖场景）则终止操作
申领已停止的环境（优先复用而非创建）
bash
```
gitpod environment start {env-id} --set-as-context --dont-wait
```
申领前检查是否有活跃的pilot：
bash
```
gitpod environment ssh {env-id} -- "pgrep -x claude || echo NO_PILOT"
```
如果存在
```
claude
```
进程，则该Pod已被占用。请选择其他环境。

undefined

5. Decision Tables

5. 决策表

Use tables whenever there are multiple paths or risk tiers.

markdown

undefined

当存在多个路径或风险等级时，请使用表格。

markdown

undefined

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

undefined

条件	风险等级	操作
补丁更新、构建通过、测试通过	低	自动合并并添加[skip ci]标记
次要版本更新、构建通过	中	标记为需要审核
主要版本更新或构建失败	高	阻止合并——需要人工审核

undefined

6. Error Handling

6. 错误处理

Explicit failure modes and what to do. Not exhaustive — only the non-obvious ones.

markdown

undefined

明确的失败模式及应对措施。无需穷尽所有情况——仅需覆盖非显而易见的场景。

markdown

undefined

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.

undefined

pgrep -x claude
返回PID —— Pod正处于任务执行中。请勿申领。选择其他环境。

bundle install
时构建失败 —— 检查Ruby版本。Lexgo需要Ruby 3.2.x。在环境内运行

ruby -v

查看。

gitpod environment ssh
超时 —— 环境可能仍在启动中。使用

gitpod environment get {env-id}

轮询，15秒后重试。

undefined

7. Critical Rules (optional)

7. 关键规则（可选）

Bullet list of absolute must-follow rules. Use when violations cause data loss, leaked resources, or security issues.

markdown

undefined

必须严格遵循的项目符号列表。当违反规则会导致数据丢失、资源泄露或安全问题时使用。

markdown

undefined

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

undefined

使用后必须释放环境 —— 停止的环境不产生费用；泄露的运行中环境会消耗额度
绝不能跳过净化步骤 —— 停止的Pod恢复时会保留陈旧的Git状态
每个环境仅运行一个Agent进程 —— 两个Agent共享Git工作目录会导致数据损坏

undefined

Description Rule

描述规则

The

description:

field is the routing signal — it determines when an operator reaches for this skill. It MUST start with an actionable trigger.

Good	Bad
"Use when running the deps pipeline for a repo."	"6-stage SEQUENTIAL ICM procedure for deps-runner."
"Use to deploy to Fly.io or configure flyctl."	"Deploy applications to Fly.io platform."
"Use when triaging Dependabot/Snyk alerts."	"Security alert triage framework."

Self-check: Does your description answer "when should I pick this skill?" If it describes how the skill works instead of when to use it, rewrite it.

Accepted trigger forms: "Use when ...", "Use to ...", "Use as ..." (for import-only skills). Mechanics notes (stage count, parallelism) belong in the skill body, not the description.

description:

字段是路由信号——决定操作者何时选择该Skill。它必须以可操作的触发词开头。

正面示例	反面示例
"运行仓库的依赖流水线时使用。"	"deps-runner的6阶段顺序ICM流程。"
"用于部署到Fly.io或配置flyctl。"	"将应用部署到Fly.io平台。"
"处理Dependabot/Snyk告警时使用。"	"安全告警处理框架。"

自检： 你的描述是否回答了“我何时应该选择这个Skill？”如果它描述的是Skill的工作方式而非使用场景，请重写。

可接受的触发形式："Use when ..."、"Use to ..."、"Use as ..."（仅导入型Skill）。技术细节（阶段数量、并行性）应放在Skill正文中，而非描述字段。

Quality Checklist

质量检查清单

Before submitting a skill, verify every item:

Frontmatter is complete and valid YAML
```
description
```
is specific enough to distinguish from similar skills
Every command in the skill was copy-pasted from a real terminal session
Error handling covers the three most common failure modes
No pseudocode — every step has a real, runnable command
Decision points have tables or explicit conditions, not "it depends"
No instructions to the user — all prose is addressed to the agent
The skill has been run at least 5 times against a real workload

提交Skill前，请验证以下所有项：

Frontmatter完整且为有效的YAML格式
```
description
```
足够具体，可与同类Skill区分
Skill中的每一条命令均从真实终端会话复制而来
错误处理覆盖了三种最常见的失败模式
无伪代码——每一步都有真实可运行的命令
决策点有表格或明确条件，而非“视情况而定”
无针对用户的指令——所有文字均面向Agent
该Skill已针对真实工作负载运行至少5次

Common Antipatterns

常见反模式

Too vague

过于模糊

markdown

undefined

markdown

undefined

Bad

反面示例

Run the appropriate command to start the environment.

运行合适的命令启动环境。

Good

正面示例

Start the environment:

bash

gitpod environment start {env-id} --set-as-context --dont-wait

undefined

启动环境：

bash

gitpod environment start {env-id} --set-as-context --dont-wait

undefined

Instructing the user instead of the agent

面向用户而非Agent的指令

markdown

undefined

markdown

undefined

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"

undefined

验证环境是否运行：

bash

gitpod environment get {env-id} --timeout 15s | grep -i "running"

undefined

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

undefined

可能被过度使用的Skill是危险的。如果存在不应调用该Skill的场景，请明确说明。

markdown

undefined

When NOT to Use

不适用场景

Major version upgrades with breaking changes — these need manual review
PRs that touch
```
schema.rb
```
or database migrations

undefined

包含破坏性变更的主版本升级——这些需要人工审核
涉及
```
schema.rb
```
或数据库迁移的PR

undefined

Hiding gotchas in prose

注意事项隐藏在正文中

Gotchas must be visually prominent. Use

> **Warning:**

, bold text, or a dedicated section. A gotcha buried in paragraph three will be missed.

注意事项必须视觉突出。使用

> **Warning:**

、粗体文字或专门章节。隐藏在第三段中的注意事项会被忽略。

Template

模板

Copy this as a starting point:

markdown

---
name: your-skill
description: One specific sentence about what this skill does and for what context.
allowed-tools: Read, Write, Bash, Glob, Grep
---

复制以下内容作为起点：

markdown

---
name: your-skill
description: 关于该Skill功能及适用场景的具体单句描述。
allowed-tools: Read, Write, Bash, Glob, Grep
---

Your Skill

One sentence: what this skill does and why it exists.

单句说明：该Skill的功能及存在意义。

When to Use

使用场景

Trigger A
Trigger B

触发条件A
触发条件B

Prerequisites

前置条件

bash

undefined

bash

undefined

verification commands

验证命令

undefined

undefined

Workflow

工作流

Step one
bash
```
command here
```
Step two — decision point

Condition Action
Case A Do X
Case B Do Y

Condition	Action
Case A	Do X
Case B	Do Y

步骤一
bash
```
命令内容
```
步骤二 —— 决策点

条件操作
场景A 执行X
场景B 执行Y

条件	操作
场景A	执行X
场景B	执行Y

Error Handling

错误处理

Common failure — what to do.

常见失败情况 —— 应对措施。

Critical Rules

关键规则

Rule 1
Rule 2

undefined

规则1
规则2

undefined