深入剖析 Agentic Awesome Skills 技能解剖学：SKILL.md 的结构、元数据与最佳实践

深入剖析 Agentic Awesome Skills 技能解剖学SKILL.md 的结构、元数据与最佳实践【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读本文档基于仓库中的技能解剖指南docs/contributors/skill-anatomy.md展开系统拆解 Agentic Awesome SkillsAAS中一个技能Skill的完整生命周期结构从目录布局、SKILL.md的 Frontmatter 元数据、正文指令组织到可选组件、规模分级与质量检查清单。读完本文你将掌握编写一个可被索引、可被校验、可被 Agent 正确解析的高质量技能文件的全部要点并了解仓库内真实技能如brainstorming、git-pushing是如何落地这些规范的。一、技能的基本目录结构在 AAS 仓库中每一个技能都存放在skills/目录下以技能名为子目录。一个典型技能目录如下skills/ └── my-skill-name/ ├── SKILL.md ← 必需技能主定义文件 ├── examples/ ← 可选示例文件 │ ├── example1.js │ └── example2.py ├── scripts/ ← 可选辅助脚本 │ └── helper.sh ├── templates/ ← 可选代码模板 │ └── template.tsx ├── references/ ← 可选参考文档 │ └── api-docs.md └── README.md ← 可选附加文档核心规则只有SKILL.md是必需的其余一切都是可选的。这一规则在仓库中得到了大量真实印证。例如 skills/git-pushing/SKILL.md 仅包含一个SKILL.md而 skills/systematic-debugging/SKILL.md 则携带了scripts/find-polluter.sh、多篇*.md参考文档与测试示例属于多文件复杂技能的代表。二、SKILL.md 的两大组成部分每个SKILL.md文件都包含两个主要部分Frontmatter元数据——文件顶部的 YAML 声明区用于索引、分类、风险评估与来源归属Content指令正文——真正指导 Agent 如何执行任务的 Markdown 内容。仓库的公开发现清单 schemas/skills-index.v1.schema.json 对索引条目定义了必需字段id、path、category、name、description、risk、source、date_added这正与 Frontmatter 中的核心字段一一对应说明元数据不仅服务于人类阅读更是生成 data/skills_index.json 等索引清单的直接数据来源。三、Part 1Frontmatter 元数据详解Frontmatter 位于文件最顶部用---包裹--- name: my-skill-name description: Brief description of what this skill does category: development risk: safe source: community source_repo: owner/repo source_type: community date_added: YYYY-MM-DD ---3.1 必需字段name作用技能的唯一标识符格式小写加连字符lowercase-with-hyphens约束必须与所在文件夹名完全一致示例stripe-integration。description作用一句话摘要格式带引号的字符串长度控制在 200 字符以内示例Stripe payment integration patterns including checkout, subscriptions, and webhooks。值得注意的是真实仓库中的技能描述往往还承担触发词的职责。例如 skills/brainstorming/SKILL.md 的描述以 Use before creative or constructive work... 开头skills/git-pushing/SKILL.md 则直接写出 Use for ordinary non-release pushes when explicitly asked to push...这些都是在帮助 Agent 判断何时激活该技能。category作用技能的主分类用于生成索引与目录面catalog surfaces格式小写分类标签示例category: development说明工具链可以为旧技能推断分类但新技能应显式声明。risk作用技能的安全等级分类可选值none|safe|critical|offensive|unknown示例risk: safe判定指南none——纯文本/推理类不执行命令或变更safe——可读取文件、运行非破坏性命令critical——会修改状态、删除文件、推送到生产环境offensive——渗透测试/红队工具必须包含 Authorized Use Only仅限授权使用警告unknown——旧版或未分类技能新技能应优先给出明确等级。仓库中的真实案例印证了风险分级的实际应用skills/copywriting/SKILL.md 声明risk: none纯写作、无命令执行而 skills/git-pushing/SKILL.md 声明risk: critical涉及提交与推送会修改远端状态。source作用技能来源归属格式URL 或短标签示例source: community、source: https://example.com/original约定如果你是原作者使用self。source_repo作用外部上游材料的规范 GitHub 仓库标识格式OWNER/REPO示例source_repo: Dimillian/Skills适用场景当技能改编或导入自外部 GitHub 仓库时必须声明。source_type作用上游仓库归属的 README 致谢分类可选值official|community|self规则self表示不需要在外部 README 仓库致谢。date_added作用技能进入本仓库的日期格式YYYY-MM-DD示例date_added: 2026-03-06说明校验工具对旧内容按建议性处理但新贡献应包含该字段。3.2 可选字段--- name: my-skill-name description: Brief description category: development risk: safe source: community source_repo: owner/repo source_type: community date_added: YYYY-MM-DD author: your-name-or-handle tags: [react, typescript, testing] tools: [claude, cursor, gemini] ---author可选作者姓名或昵称tags可选用于检索与归类的标签数组tools可选技能适配的 Agent/工具列表如[claude, cursor, gemini]license可选上游源材料的 SPDX 许可证标识例如MIT、Apache-2.0、CC-BY-4.0。当source_repo指向已知许可证下的材料时声明省略该字段表示对下游工具许可证未经核验license_source可选上游许可证文件的直接 URL与license搭配以便自动化工具核验若上游仓库没有 LICENSE 文件应省略此字段。这些可选字段在真实仓库中广泛使用例如 skills/2slides-ppt-generator/SKILL.md 同时声明了author、tags: [presentations, slides, powerpoint, ...]与tools: [claude, cursor, gemini, codex, antigravity]。3.3 来源致谢契约Source-credit contract源自外部 GitHub 的技能应同时声明source_repo与source_typesource_type: official表示该仓库必须出现在README.md的### Official Sources之下source_type: community表示该仓库必须出现在README.md的### Community Contributors之下source: self加上source_type: self是仓库原创内容的正确形态PR 的 CI 会检查变更技能对应的 README 致谢覆盖情况一旦声明了source_repo缺少或错误分桶的仓库致谢会阻塞 PR 合并。四、Part 2正文内容组织Frontmatter 之后是技能的实际指令内容推荐按以下结构组织1. 标题H1# Skill Title使用清晰、有描述性的标题通常与技能名一致或在其基础上扩展。2. 概述Overview## Overview A brief explanation of what this skill does and why it exists. 2-4 sentences is perfect.3. 使用时机When to Use## When to Use This Skill - Use when you need to [scenario 1] - Use when working with [scenario 2] - Use when the user asks about [scenario 3]为什么重要帮助 AI 判断何时激活该技能。skills/git-pushing/SKILL.md 提供了一个极佳的实践样例它列出 Explicitly asks to push changes、Mentions saving work to remote、Completes a feature and wants to share it 等明确触发场景。4. 核心指令Core Instructions## How It Works ### Step 1: [Action] Detailed instructions... ### Step 2: [Action] More instructions...这是技能的心脏——清晰、可执行的步骤。5. 示例Examples## Examples ### Example 1: [Use Case] javascript // Example code ### Example 2: [Another Use Case] javascript // More code 示例的意义向 AI 精确展示好的输出长什么样。6. 最佳实践Best Practices## Best Practices - ✅ Do this - ✅ Also do this - ❌ Dont do this - ❌ Avoid this7. 常见陷阱Common Pitfalls## Common Pitfalls - **Problem:** Description **Solution:** How to fix it8. 安全与安全须知Security Safety Notes如果技能包含以下内容必须在收尾前增加专门的安全小节shell 命令或命令式示例远程拉取/安装或令牌使用指引文件变更、破坏性操作或特权操作。## Security Safety Notes - This is safe/unsafe scope - Required confirmation or authorization - Example allowlist notes (if needed): !-- security-allowlist: ... --9. 关联技能Related Skills## Related Skills - other-skill - When to use this instead - complementary-skill - How this works together五、撰写有效指令的三个原则使用清晰、直接的语言❌ 差You might want to consider possibly checking if the user has authentication.✅ 好Check if the user is authenticated before proceeding.使用动作动词❌ 差The file should be created...✅ 好Create the file...做到具体❌ 差Set up the database properly.✅ 好1. Create a PostgreSQL database 2. Run migrations: npm run migrate 3. Seed initial data: npm run seed六、可选组件scripts / examples / templates / referencesScripts 目录技能需要辅助脚本时可放在scripts/下scripts/ ├── setup.sh ← 安装自动化 ├── validate.py ← 校验工具 └── generate.js ← 代码生成器在 SKILL.md 中引用它们Run the setup script: bash bash scripts/setup.sh 仓库中的 skills/git-pushing/SKILL.md 就是这样组织辅助脚本的——它引用scripts/smart_commit.sh并明确要求先解析安装目录再用绝对路径调用避免假设当前工作目录就是目录仓库bash skill-directory/scripts/smart_commit.sh bash skill-directory/scripts/smart_commit.sh feat: add feature bash skill-directory/scripts/smart_commit.sh fix: scope change -- path/to/fileExamples 目录存放能演示技能的实战示例examples/ ├── basic-usage.js ├── advanced-pattern.ts └── full-implementation/ ├── index.js └── config.jsonTemplates 目录存放可复用的代码模板templates/ ├── component.tsx ├── test.spec.ts └── config.json在 SKILL.md 中引用Use this template as a starting point: typescript {{#include templates/component.tsx}} References 目录存放外部文档或 API 参考references/ ├── api-docs.md ├── best-practices.md └── troubleshooting.mdskills/systematic-debugging/SKILL.md 是多文件复杂技能的典型它同时包含condition-based-waiting.md、defense-in-depth.md、root-cause-tracing.md等参考文档与find-polluter.sh辅助脚本。七、技能规模分级指南规模Frontmatter正文字数章节要求附加内容最小可用技能Minimum Viable Skill标准字段name、description、category、risk、source、date_added100–200 词Overview Instructions无标准技能Standard Skill标准字段300–800 词Overview When to Use Instructions Examples无综合技能Comprehensive Skill标准字段外加source_repo/source_type外部派生时及有用处的可选字段800–2000 词全部推荐章节Scripts、examples、templates经验法则从小处起步根据反馈逐步扩展。八、格式最佳实践代码块始终指定语言例如javascript列表保持格式一致嵌套使用缩进强调重要术语用粗体强调用斜体命令/代码用code链接Link text标准写法。九、质量检查清单Quality Checklist在最终确定技能前逐项核对内容质量指令清晰可执行示例真实有用无拼写与语法错误技术准确性已核验结构Frontmatter 是合法 YAMLname与文件夹名一致章节逻辑组织合理标题层级正确H1 → H2 → H3完整性Overview 解释为什么Instructions 解释怎么做Examples 展示是什么边界情况已覆盖可用性初学者能跟随专家觉得有用AI 能正确解析解决了真实问题十、真实技能解剖以brainstorming为例文档对 skills/brainstorming/SKILL.md 做了逐段分析这里完整呈现--- name: brainstorming description: You MUST use this before any creative work... ---分析结论✅ 命名清晰✅ 描述带有强触发语义MUST use✅ 说明了使用时机# Brainstorming Ideas Into Designs ## Overview Help turn ideas into fully formed designs...分析结论✅ 标题清晰✅ 概述简洁✅ 说明了价值主张## The Process **Understanding the idea:** - Check out the current project state first - Ask questions one at a time分析结论✅ 拆分为清晰阶段✅ 具体、可执行的步骤✅ 易于跟随实际读取该文件可以看到更完整的设计它包含Operating Mode操作模式、Understanding Lock理解锁定硬门禁、Decision Log决策日志、Exit Criteria退出条件等严格流程全文围绕禁止在确认前实现这一核心纪律展开是综合技能的教科书级范例。十一、进阶模式Advanced Patterns条件逻辑Conditional Logic## Instructions If the user is working with React: - Use functional components - Prefer hooks over class components If the user is working with Vue: - Use Composition API - Follow Vue 3 patterns渐进式披露Progressive Disclosure## Basic Usage [Simple instructions for common cases] ## Advanced Usage [Complex patterns for power users]交叉引用Cross-References## Related Workflows 1. First, use brainstorming to design 2. Then, use writing-plans to plan 3. Finally, use test-driven-development to implement十二、技能有效性评估指标如何判断一个技能是否优秀清晰度测试Clarity Test不熟悉该主题的人能否跟上是否存在含糊的指令完整性测试Completeness Test是否覆盖了正常路径happy path是否处理了边界情况是否涉及错误场景有用性测试Usefulness Test是否解决真实问题你自己会用它吗是否节省时间或提升质量十三、从现有技能中学习入门级样例skills/brainstorming/SKILL.md —— 结构清晰skills/git-pushing/SKILL.md —— 简单聚焦skills/copywriting/SKILL.md —— 示例优秀。进阶级样例skills/systematic-debugging/SKILL.md —— 内容全面skills/react-best-practices/SKILL.md —— 多文件组织skills/loki-mode/SKILL.md —— 复杂工作流。以 skills/react-best-practices/SKILL.md 为例它展示了元数据驱动索引的进阶形态在 Frontmatter 之外正文直接用表格列出 8 个按优先级排序的规则类别如Eliminating Waterfalls为 CRITICAL、Bundle Size Optimization为 CRITICAL、Advanced Patterns为 LOW并用async-、bundle-、server-等统一前缀管理几十条规则极大方便了检索与自动重构工具的使用。十四、实用技巧Pro Tips从 When to Use 章节开始写——它明确了技能存在的目的先写示例——帮助你理解自己到底在教什么用 AI 实测——提交前确认它真的能工作获取反馈——请他人评审你的技能持续迭代——技能会随使用不断改进。十五、常见错误与修正❌ 错误 1过于含糊## Instructions Make the code better.✅ 修正## Instructions 1. Extract repeated logic into functions 2. Add error handling for edge cases 3. Write unit tests for core functionality❌ 错误 2过于复杂## Instructions [5000 words of dense technical jargon]✅ 修正拆分为多个技能或使用渐进式披露。❌ 错误 3没有示例## Instructions [Instructions without any code examples]✅ 修正至少添加 2–3 个贴近现实的示例。❌ 错误 4信息过时Use React class components...✅ 修正保持技能与当前最佳实践同步。十六、下一步行动阅读 3–5 个现有技能体会不同风格参考技能模板 docs/contributors/skill-template.md 与贡献规范 CONTRIBUTING.md为你熟悉的内容创建一个简单技能用你的 AI 助手实测它通过 Pull Request 分享它。记住每位专家都曾是初学者。从小处开始从反馈中学习持续改进。结语技能的解剖学知识是 AAS 生态的基石SKILL.md的 Frontmatter 让数千个技能可以被索引、分类、风险评估与来源追溯参见 schemas/skills-index.v1.schema.json 中category、risk、source、date_added等必需字段的定义而正文的指令组织方式则直接决定了 Agent 能否正确理解并执行任务。结合仓库中的真实技能样例与 docs/contributors/skill-template.md 提供的标准模板你完全可以在几分钟内写出第一个结构合格、语义清晰的技能文件——先让它能被 AI 正确解析再逐步扩充到综合级别。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考