skill-management

技能管理

概述

指导如何创建、审核和验证符合 Agent Skills 开放标准（https://agentskills.io）的 Agent 技能，涵盖从搭建新技能到进行生产级审查的完整生命周期。

适用场景： 创建技能、改进描述以提高可发现性、重构技能以实现渐进式披露、执行质量审计、验证清单与实现是否一致。

不适用场景： 编写应用代码、常规 Markdown 编辑、与技能编写无关的项目管理。

快速参考

任务	方法	要点
技能目录	skill-name/SKILL.md + 可选目录	只需提供 SKILL.md；scripts/、references/、assets/ 均为可选
Frontmatter name	小写字母、连字符、4-64 个字符	必须与目录名称一致，不能以 - 开头或结尾，也不能包含 --
Frontmatter description	1-1024 个字符，包含触发短语	使用第三人称语态，包含「适用场景」
渐进式披露	元数据 -> SKILL.md -> references/scripts	将 SKILL.md 控制在 500 行以内；将详细内容移至 references
描述结构	第 1 段：用途 + 特性，第 2 段：触发条件	使用主动语态，列出技术名称，包含错误关键词
有效描述	250-350 个字符，具体且易于发现	使用「构建 X」，而非「此技能可帮助你构建 X」
参考文件	references/topic.md，含 frontmatter	最多 500 行，内容自包含，文件名采用 kebab-case
质量审计	9 阶段系统化审查	检查标准、官方文档、代码准确性和文件间的一致性
严重程度	严重 / 高 / 中 / 低	基于证据进行分类，并附上链接
验证评分	准确性、前置条件、效果的平均分	通过要求评分 >= 0.8，且不存在高严重程度问题
排除的文件	README.md、metadata.json、_* 文件	Skills CLI 在安装过程中会移除这些文件

常见错误

错误	正确做法
在技能目录中包含 README.md	Skills CLI 安装时会排除 README.md；只使用 SKILL.md
描述含糊，缺少用于发现的关键词	包含具体技术、3-5 个「适用场景」以及 2-3 条错误消息
重复 Agent 已掌握的知识	聚焦 Agent 容易出错的边缘情况、平台差异和注意事项
将所有内容都放在 SKILL.md 中，不采用渐进式披露	将 SKILL.md 控制在 500 行以内；把代码示例移至 references/
列出磁盘上不存在的捆绑文件	审核时核实所有跨文件引用；失效链接会损害信任
在描述中使用被动语态或第一人称	使用第三人称主动语态：「构建 X」，而非「此技能可帮助你构建 X」
使用 README.md 设置自动触发关键词	发现机制依赖 description 字段中的触发词，而非 README.md
引用不存在的脚本或命令	只引用技能目录中实际存在的脚本和命令

委派

• 技能发现和关键词研究：使用 Explore Agent
• 多技能审核和跨文件一致性检查：使用 Task Agent
• 技能架构和目录结构规划：使用 Plan Agent

如果有 find-skills 技能，请将技能发现、安装和 CLI 使用委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s find-skills -a claude-code -y

参考资料

• 创建技能：结构、frontmatter、描述、渐进式披露
• 审核技能：9 阶段审查、严重性分类、修复决策
• 验证技能：实现与清单对照、偏差检测、通过标准