How to Write Your First Agent Skill

如何编写你的第一个 Agent 技能

You have house rules for your coding agent: how commit messages should look, what a code review should check, how meeting notes should be structured. So you paste them into the chat at the start of every session — and by message ten the agent has drifted anyway. Next session, you paste again. The problem is not memory. The instructions live in your clipboard instead of in a file the agent loads every time. A skill is that file. 你为你的编程 Agent 制定了“家规”：提交信息应该是什么样子的、代码审查应该检查什么、会议纪要应该如何组织。于是，你在每次会话开始时都把这些规则粘贴到聊天框里——但聊到第十条消息时，Agent 往往已经偏离了要求。下一次会话，你又得重新粘贴。问题不在于记忆力，而在于这些指令存在你的剪贴板里，而不是 Agent 每次启动时都会加载的文件中。所谓的“技能（Skill）”，指的就是那个文件。

What a skill is

什么是技能

A skill is a folder containing one file: SKILL.md. It has two parts. The YAML frontmatter carries two fields — a name and a description. The description is the trigger: the agent scans the descriptions of its skills to decide which ones apply to your request. So the description does two jobs — say what the skill does, and name the situations where it fires. Write it as “does X. Use when the user asks for Y.” The body is plain markdown: the workflow, the rules, an example. No code, no config beyond the frontmatter. 技能是一个包含单个文件 SKILL.md 的文件夹。它由两部分组成。YAML 元数据（frontmatter）包含两个字段：名称（name）和描述（description）。描述是触发器：Agent 会扫描其技能的描述，以决定哪些技能适用于你的请求。因此，描述承担了两项任务——说明技能的功能，并指明触发该技能的情境。请将其写成“执行 X。当用户要求 Y 时使用。”正文是纯 Markdown 格式：包含工作流、规则和示例。除了元数据外，不需要任何代码或配置。

Teardown: a commit-message skill

拆解：一个提交信息（commit-message）技能

The smallest skill in my pack generates commit messages, and it shows every part doing a job. Its frontmatter, verbatim: 我工具包中最小的技能是生成提交信息，它展示了每个部分是如何发挥作用的。以下是它的元数据原文：

---
name: git-commit-message
description: "Generates conventional-commit messages from staged changes: type prefix + English imperative subject (≤50 chars) + optional body explaining why. Use when the user asks to write, generate, or polish a git commit message."
---

The workflow is five numbered steps, in execution order: 工作流包含五个按执行顺序编号的步骤：

1. Look at the changes (git status —short, git diff —cached —stat). If nothing is staged, stop and ask — never invent a message out of nothing.
2. 查看变更（git status --short, git diff --cached --stat）。如果没有暂存内容，则停止并询问——绝不要凭空捏造信息。
3. Pick exactly one type prefix: feat, fix, docs, refactor, test, chore. A change that mixes types gets split into two commits, not averaged into one.
4. 准确选择一个类型前缀：feat, fix, docs, refactor, test, chore。如果变更混合了多种类型，应拆分为两次提交，而不是合并成一次。
5. Write the subject: type + imperative phrase, ≤50 characters. Empty subjects like “update code” are banned.
6. 编写主题：类型 + 祈使短语，不超过 50 个字符。禁止使用“更新代码”这类空洞的主题。
7. Write an optional body: 1–3 lines explaining why, not a play-by-play of how.
8. 编写可选的正文：1-3 行，解释“为什么”做这个变更，而不是逐行描述“怎么”做的。
9. Output a ready-to-run git commit command, not bare text the user has to assemble.
10. 输出可直接运行的 git commit 命令，而不是需要用户手动拼凑的纯文本。

Then come the rules that encode judgment — the things you would otherwise keep correcting in review: 接下来是编码了判断逻辑的规则——这些通常是你需要在审查中反复纠正的内容：

• The subject is for skimmers; the body is for future-you in three months. Keep the two jobs separate.
• 主题是给快速浏览者看的；正文是给三个月后的你自己看的。保持这两项任务分离。
• No meta-commentary in the message (“generated by AI”, etc.) — the message is about the change, nothing else.
• 信息中不要包含元评论（如“由 AI 生成”等）——信息只应关于变更本身，别无他物。

And one worked example, with the expected output: 以及一个带有预期输出的示例：

git commit -m "feat: add CAPTCHA verification to login endpoint" -m "Blocks automated credential stuffing; CAPTCHA valid 5 minutes, account locks 10 minutes after 3 failures."

Finally, the anti-patterns — the failure modes, named explicitly: 最后是反模式（Anti-patterns）——明确指出的失败场景：

• Writing a message for an empty staging area: no diff, no commit message.
• 为空的暂存区编写信息：没有差异，就没有提交信息。
• Catch-all chore: labeling every feat and fix as chore until the type system means nothing.
• 万能的 chore：把所有的 feat 和 fix 都标记为 chore，直到类型系统失去意义。
• Novel-length subjects that praise the change instead of naming it.
• 小说长度的主题，只顾赞美变更而不说明变更内容。
• Body as implementation log (“first changed line 20 of a.py, then b.py…”) — the diff already shows that; the body explains why.
• 将正文写成实现日志（“首先修改了 a.py 的第 20 行，然后是 b.py……”）——差异对比已经展示了这些，正文应该解释原因。

Each part earns its place. The description decides triggering. The numbered steps fix the order of operations and include a stop condition. The rules hold the judgment calls. The example anchors the output format better than a paragraph of prose. The anti-patterns tell the agent what to refuse. 每一部分都有其存在的意义。描述决定了触发机制；编号步骤固定了操作顺序并包含停止条件；规则承载了判断逻辑；示例比长篇大论更能锚定输出格式；反模式则告诉 Agent 应该拒绝什么。

Writing your own

编写你自己的技能

Pick a workflow you have explained at least three times. Repetition is the selection criterion. Write the description first. If you cannot write a clean trigger, the skill’s scope is too wide. Write the workflow as numbered steps in execution order, with stop conditions for the cases where it should not proceed. Add the rules you always end up correcting — naming, format, what to do when the input is ambiguous. Add one worked example — real input, expected output, no placeholders. Add the anti-patterns. The ways this workflow goes wrong are as instructive as the steps. Keep it short. Two minutes to read. If a rule never fires, delete it; a short, accurate skill beats a long, stale one. 挑选一个你至少解释过三次的工作流。重复性是选择的标准。先写描述，如果你写不出清晰的触发条件，说明该技能的范围太广了。将工作流写成按执行顺序编号的步骤，并为不应继续的情况设置停止条件。添加你总是需要纠正的规则——命名、格式、输入模糊时该怎么办。添加一个实际示例——真实的输入、预期的输出，不要使用占位符。添加反模式，工作流出错的方式和步骤本身一样具有指导意义。保持简短，两分钟内读完。如果某条规则从未被触发，就删掉它；一个简短、准确的技能胜过一个冗长、过时的技能。

Using it

如何使用

Drop the folder into your agent’s skills directory, and the agent picks it up by matching the description — no further configuration. If you want working examples first, the five skills in the pack this teardown came from are free and MIT-licensed: commit messages, code review, meeting minutes, technical proofreading, and structured deep research. 将文件夹放入 Agent 的技能目录中，Agent 就会通过匹配描述自动识别它——无需进一步配置。如果你想先看看现成的示例，本文拆解的工具包中的五个技能是免费且采用 MIT 协议开源的：提交信息、代码审查、会议纪要、技术校对和结构化深度研究。

Repo: https://github.com/alapha888/agent-skills-en npx skills add alapha888/agent-skills-en

The structure is the stable part; the rules are yours. Take the workflow you explained three times this week, and write it down once. 结构是稳定的部分，规则则属于你。把你这周解释过三次的工作流拿出来，写下来一次吧。