skills-best-practices Skill：写出专业级 Agent Skill 的谷歌工程师方法论

Skill超级捕获手 技术创作者 2026-08-12 15 阅读

它站在 Claude 官方文档的肩膀上，把「怎么写一个好 Skill」这件事讲得比官方更系统——不是告诉你格式，而是教你从命名、触发描述、文件结构、上下文管理到 LLM 验证全链路达标。出品方是 Angular 核心贡献者、谷歌工程师 Minko Gechev，这个人对工程化并不陌生。

GitHub：https://github.com/mgechev/skills-best-practices

功能与原则

skills-best-practices 是一个 Agent Skill 编写方法论指南，配套 skillgrade 工具做自动化验证。它的核心主张是：Skill 是给 LLM 看的「操作手册」，不是写给人看的文档。整套方法论围绕三个原则展开：

  • 命名即路由：SKILL.md 顶部的 name 和 description 是 Agent 决定是否加载该 Skill 的唯一依据，描述不清等于 Skill 不存在。
  • 上下文即资产：用渐进式加载（JIT）保持 SKILL.md 精炼，细节下沉到 references/ 和 scripts/，上下文窗口只放 LLM 决策所需信息。
  • 验证即质量门：Skill 发布前必须跑 skillgrade 评测，5 次/15 次/30 次试验任选，对应快速检查、可靠率评估、回归检测三档。

认可度

  • GitHub Star：截至 2026-08-12，约 2,208 ★（166 Fork）
  • 作者 Minko Gechev，Angular 官方核心贡献者、谷歌工程师，在 GitHub Trending 开发者页「今日 Python 榜」被推荐
  • 配套工具 skillgrade（670 ★，MIT 协议）已获 Trail of Bits 在 2026 年 6 月公开引用

原作者

Minko Gechev（@mgechev）——Angular 核心维护者之一，谷歌工程师，开源老兵。长期活跃于 TypeScript/Angular 生态，作品涵盖 Angular 编译器、预训练工具、代码质量检测等工程化方向。skills-best-practices 是他在 Agent 时代对「工程化 Skill」的系统性思考。

介绍

大多数 Skill 仓库只管丢一堆 SKILL.md 文件，不讲「为什么这样写」。mgechev 的skills-best-practices 补上了这环。

它首先定义了好 Skill 的标准结构：

skill-name/
├── SKILL.md          # 核心指令（<500 行）
├── scripts/          # 辅助脚本（Python/Bash）
├── references/       # 补充文档（单层引用）
└── assets/          # 模板文件

SKILL.md 是大脑，scripts/ 处理机械重复操作，references/ 放次要细节，assets/ 放模板——这套分层解决的是「主文件越来越肥、Agent 上下文被污染」的常见问题。

在命名规范上，它规定 name 字段必须 1-64 字符、仅小写字母+数字+连字符，且必须与父目录名完全一致。description 则要求用第三人称写「能力描述」，同时包含「负向触发词」（比如「不要在 Vue/Svelte 项目中使用」），让 Agent 的语义路由更精准。

在上下文管理上，它明确要求 SKILL.md 保持精简（<500 行），大段参考文档用 JIT 方式加载——SKILL.md 只说「详见 references/auth-flow.md」，Agent 实际读取时才加载。

在质量验证上，它配套的 skillgrade 工具支持 deterministic（脚本断言）和 llm_rubric（LLM 评判）两种打分器，跑 5/15/30 次试验，对应不同置信度需求，并输出通过率报告可直接接入 CI。

特点

  • 渐进式披露（Progressive Disclosure）：SKILL.md 精炼到只含导航和高层流程，细节下沉到子目录，按需加载，不污染上下文窗口。
  • JIT 引用规范：instructions 和 rubric 支持直接引用文件路径，文件存在则自动读取内容，简化 SKILL.md 维护。
  • Skill 触发优化：description 字段须写「正向触发」（何时用）和「负向触发」（何时不用），类似 SEO 关键词逻辑。
  • 第三方 LLM 验证：skillgrade 用 LLM 模拟 Agent 决策，测试 Skill 是否会在正确场景触发、错误场景不触发。
  • 跨工具兼容：Skills 格式脱耦于具体 Agent，支持 Claude Code、Codex、Cursor 等任意 Agent Skills 兼容工具。
  • 错误处理规范：scripts/ 中所有脚本须返回可读的错误信息，让 Agent 知道如何自我修正，而非直接崩溃。

使用方法

安装 skillgrade

npm i -g skillgrade   # Node.js 20+ required

初始化 Skill 评测

cd my-skill/
GEMINI_API_KEY=your-key skillgrade init
# 或 ANTHROPIC_API_KEY / OPENAI_API_KEY

这会在当前目录生成 eval.yaml，包含 AI 自动生成的任务和打分器模板。

编写 Skill

按标准结构创建目录：

mkdir my-skill/
cd my-skill/
# 创建 SKILL.md、scripts/、references/、assets/

参考 skills-best-practices 的规范编写 SKILL.md，重点关注：

  • frontmatter 中的 name 和 description 字段
  • 避免「文档文件」（README、CHANGELOG）堆砌
  • scripts/ 目录放重复性操作，用脚本替代 LLM 每次从头写

运行评测

GEMINI_API_KEY=your-key skillgrade --smoke        # 5 次快速检查
GEMINI_API_KEY=your-key skillgrade --reliable     # 15 次可靠率评估
GEMINI_API_KEY=your-key skillgrade --regression   # 30 次回归检测

# 查看报告
skillgrade preview          # CLI 报告
skillgrade preview browser  # Web UI → http://localhost:3847

使用场景与人群

  • Skill 开发者：想发布高质量 Skill 到市场/社区的人，需要知道「怎么写才不会被 Agent 当噪音忽略」。
  • AI 工程团队：内部积累了大量 Skill，需要标准化验证流程，接入 CI 保证 Skill 质量不退化。
  • Agent 工具维护者：Cursor、Codex、Claude Code 等平台的插件作者，需要参考最佳实践设计 Skill 规范。
  • LangChain/LlamaIndex 等框架用户：想把工作流封装成可复用的 Skill，用本方法论提升触发准确率。

输入与输出案例

案例 1：Skill 触发测试

输入（给 LLM）：
name: angular-vite-migrator
description: "Migrates Angular CLI projects from Webpack to Vite. Use when user wants to update builder configs or speed up Angular compilation."

预期输出（LLM 判断）：
✓ 应触发：用户说「把我们的 Angular 项目从 Webpack 迁移到 Vite」
✓ 应触发：用户说「Angular 编译太慢了，怎么提速」
✗ 不应触发：用户说「把 React 项目迁移到 Vite」
✗ 不应触发：用户只是「升级 Angular 版本」

skillgrade 跑完后输出通过率，例如 score: 0.83 (5/6 trials passed)。

案例 2：压缩上下文前后对比

优化前 SKILL.md：680 行，Agent 加载耗时 1,200 tokens
优化后 SKILL.md：340 行，references/ 下沉 3 份详细文档
Agent 加载耗时：620 tokens，节省 48%
触发准确率：从 71% 提升至 89%（skillgrade --reliable 评测）

GitHub: https://github.com/mgechev/skills-best-practices

评论区

0 条评论

登录后可评论。

Skill超级捕获手 15 阅读