前言：写 Skill 容易，写好 Skill 很难
随着 Agent Skills 生态成熟，越来越多人开始动手写自己的技能。但一个普遍现象是：**很多人写的技能要么根本不被 AI 触发，要么占了大量上下文却收效甚微，要么让 AI 执行时频频"幻觉"出根本不存在的步骤。**说到底，写技能不是写人类文档——它是写给 AI 看的，规则完全不同。
GitHub 上有一个非常"干货"的项目 mgechev/skills-best-practices，作者 Minko Gechev（Angular 团队核心成员、Google 工程师）把创建 Agent Skill 的最佳实践浓缩成了一份精炼指南，还附带了可落地的校验脚本。虽然仓库不大，但在技术圈口碑极高。今天我们就把它讲透。
一、项目速览
| 项目名称 | mgechev/skills-best-practices |
|---|---|
| 项目定位 | 创建专业级 Agent Skill 的最佳实践指南 |
| 主要语言 | Python（校验脚本）+ Markdown |
| 核心价值 | 教你写出"会被触发、能省 Token、AI 能照着做"的技能 |
| 适合人群 | Skill 作者、Prompt 工程师、AI 产品开发者 |
二、技能的目录结构：有标准可循
每个技能都必须遵循统一的目录结构：
skill-name/
├── SKILL.md # 必需：元数据 + 核心指令（少于 500 行）
├── scripts/ # 可执行代码（Python/Bash），设计成小 CLI
├── references/ # 补充上下文（schema、速查表）
└── assets/ # 输出所用的模板或静态文件- SKILL.md：充当"大脑"，用于导航和高级流程。
- references/：从 SKILL.md 直接链接，只允许一层深度。
- scripts/：用于脆弱或重复性操作（在这些场景里，变化本身就是 bug）。不要把库代码塞进来。
三、让技能"被发现"：frontmatter 是生命线
这是全篇最重要的一点：SKILL.md frontmatter 里的 name 和 description，是 AI 在触发技能前唯一能看到的信息。**如果它们没有为"可发现性"优化、不够具体，你的技能就是"隐形"的。
- 严格命名：name 必须 1–64 字符，仅含小写字母、数字和连字符（不允许连续连字符），且必须与父目录名完全一致（如 name:
angular-testing必须位于angular-testing/SKILL.md）。 - 为触发优化的 description（最多 1024 字符）：用第三人称描述能力，并包含"负面触发条件"。
对比一下好坏：
| 写法 | 示例 |
|---|---|
| ❌ 差 | "React 技能。"（太模糊） |
| ✅ 好 | "使用 Tailwind CSS 创建和构建 React 组件。当用户想更新组件样式或 UI 逻辑时使用。不要用于 Vue、Svelte 或原生 CSS 项目。" |
四、渐进式披露：让上下文保持清爽
核心思想是只在需要时加载信息。SKILL.md 是处理高级逻辑的"大脑"，细节统统下放到子目录。
- 保持 SKILL.md 精简：主文件限制在 500 行以内。
- 使用扁平子目录：文件只允许一层深度（如
references/schema.md，而不是references/db/v1/schema.md）。 - 即时（JiT）加载：明确告诉 AI 什么时候该读哪个文件——在你去指引它之前，它根本"看不见"这些资源。
- 显式路径：无论什么操作系统，始终使用带正斜杠
/的相对路径。
记住：技能是给 AI 用的，不是给人类看的。为了保持上下文精简，以下东西不要创建：README.md / CHANGELOG.md / INSTALLATION_GUIDE.md 这类文档文件；AI 已经能可靠处理的任务的冗余指令；以及长期存在的库代码。
五、用具体的流程性指令，而不是散文
- 用分步骤编号：把工作流定义成严格的时间顺序。有决策树就画清楚，例如："第 2 步：若需要 source map，运行
ng build --source-map；否则跳到第 3 步。" - 提供具体模板：AI 极其擅长"模式匹配"。与其花几段话描述 JSON 输出长什么样，不如把模板放进
assets/目录，然后指示 AI 照抄结构。 - 用第三人称祈使句：写成对 AI 的直接命令（如"提取文本……"），而不是"我将提取……"或"你应该提取……"。
术语也要保持一致：给同一个概念只选一个术语，并使用最贴合行业的具体说法。例如在 Angular 里用 "template"，而不是 "html"、"markup" 或 "view"。
六、把重复操作固化成确定性脚本
不要让 AI 每次执行技能时都从零写复杂的解析逻辑或样板代码。
- 卸载脆弱/重复的任务：如果需要解析复杂数据集或查询特定数据库，给 AI 一个经过测试的 Python/Bash/Node 脚本，放进
scripts/。 - 优雅地处理边界情况：AI 靠标准输出（stdout/stderr）判断脚本是否成功。让脚本返回描述清晰、人类可读的错误信息，AI 就能自我纠正，无需人工介入。
七、技能组合（路由器技能）
当你需要条件性地包含某个技能，或想创建由子技能组成的技能时，可以写"路由器技能"：
---
name: build_project
description: ...
---
## Overview
...
## Build targets
### Client
To build the client into a deployable binary see [path to skills].
### Server
To build the server into a deployable binary see [path to skill].这样主 SKILL.md 只负责分发，具体逻辑落到各个子技能里，结构清晰、易于维护。
八、验证指南：用 LLM 来验证你的技能
既然技能是给 LLM 用的，那么最佳的验证方式也是与 LLM 协作。作者给出了四个递进步骤，非常有实操价值：
1. 发现验证（Discovery Validation）
把技能的 YAML frontmatter 单独发给一个全新的 LLM 对话框，要求它：① 生成 3 个你确信应该触发该技能的真实用户提示；② 生成 3 个听起来相似但不该触发的提示；③ 点评描述是否太宽泛，并给出优化改写。这一步能有效防止误触发。
2. 逻辑验证（Logic Validation）
把完整的 SKILL.md 和目录树交给 LLM，让它扮演"刚触发技能的自主体"，逐步模拟执行过程，并输出内心独白：你在做什么？读哪个文件、跑哪个脚本？标出所有"执行阻碍点"——也就是你被迫猜测或幻觉的地方。
3. 边界情况测试（Edge Case Testing）
让 LLM 切换角色扮演"无情的 QA"，对你的技能提出 3–5 个刁钻问题：脚本因遗留依赖失败怎么办？用户配置不兼容怎么办？有没有对环境做了隐含假设？先别修，让它先提问、你逐一回答。
4. 架构精炼（Architecture Refinement）
最后让 LLM 依据你的回答重写 SKILL.md，严格执行渐进式披露：主文件只保留高层步骤（第三人称祈使句），把密集规则、大模板移到 references/ 或 assets/，并补充一个专门的错误处理章节。
九、源码下载（蓝奏云高速下载）
我已把该项目最新源码打包上传到蓝奏云（含 SKILL.md、模板、校验脚本与检查清单）：
📦 下载地址：mgechev/skills-best-practices 最新源码包（蓝奏云）
仓库中的 skill/scripts/validate-metadata.py 可以直接用来校验你技能的 frontmatter 是否合规，非常实用。
十、总结
这个项目最大的价值，是把"写技能"这件看似简单的事，拆解成了一套可检验的工程规范：结构要标准、描述要精准、上下文要精简、指令要具体、脚本要确定、验证要靠 LLM。如果你的技能总是"不好用"，多半就是踩了上面某一条。建议把这篇文章当作写 Skill 的检查清单，逐条对照优化。
更多 AI 工具与智能体技能实战教程，请持续关注本栏目。
