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/vietnamese/SKILL_ANATOMY.vi.md及其英文母本 docs/contributors/skill-anatomy.md为主体系统拆解一个 Agentic Skill 的完整解剖结构目录布局、SKILL.md的 frontmatter 元数据字段、内容章节编排、写作技巧、规模分级与质量检查清单并结合作品仓库中的 skills-index schema、skill-score schema、data/skills_index.json 以及 brainstorming、git-pushing 等真实 Skill 源码讲透一个能被 AI 正确解析、被目录索引、被质量门禁放行的 Skill 长什么样。读完你将掌握从零编写、校验并提交一个合格 Skill 的完整方法论。一、Skill 的基本目录结构在 agentic-awesome-skills 仓库中每个 Skill 都占据skills/下的一个独立目录目录名即 Skill 标识。规范推荐的目录骨架如下skills/ └── my-skill-name/ ├── SKILL.md ← 必选Skill 主定义文件 ├── examples/ ← 可选示例文件 │ ├── example1.js │ └── example2.py ├── scripts/ ← 可选辅助脚本 │ └── helper.sh ├── templates/ ← 可选代码模板 │ └── template.tsx ├── references/ ← 可选参考资料 │ └── api-docs.md └── README.md ← 可选补充文档核心规则只有SKILL.md是必选的其余一切皆为可选。这条规则保证了仓库的进入门槛足够低——一个最小可用 Skill可以只有单个文件而复杂 Skill 则可以演化成多文件、带脚本和模板的完整工程。例如仓库中 skills/react-best-practices/SKILL.md 就是典型的多文件形态而 skills/systematic-debugging/SKILL.md 则以全面著称。二、SKILL.md 的两大组成部分每个SKILL.md都由两个主要部分构成Frontmatter元数据位于文件最顶部、被一对---包裹的 YAML 块用于向目录索引与工具链描述 Skill 的身份、风险等级与来源。内容指令frontmatter 之后的正文是真正写给 AI 阅读并执行的操作指南。下面分别深入拆解。三、Frontmatter 详解必填字段frontmatter 是 Skill 的身份证其标准形态如下--- name: my-skill-name description: Mô tả ngắn gọn về chức năng của skill này category: development risk: safe source: community date_added: 2026-06-25 ---1.name含义Skill 的标识符。格式kebab-case小写字母加连字符如stripe-integration。要求必须与目录名完全一致。这一点也被目录生成器强制约束——见下文 schema 部分。示例stripe-integration、git-pushing。2.description含义一句话功能摘要。格式带引号的字符串。长度建议控制在 150 字符以内英文母本规范放宽至 200 字符。示例Stripe payment integration patterns including checkout, subscriptions, and webhooks。实战提示description 是 AI 决定何时激活该 Skill的主要依据越具体、越能描述触发场景越好。仓库中 skills/brainstorming/SKILL.md 的 description 就用Use before creative or constructive work这类强触发词来引导激活时机。3.category含义Skill 的主分类用于生成目录索引catalog surfaces。格式小写分类标签。示例development、security、testing、infrastructure。说明工具链可以为历史遗留 Skill 推断分类但新提交的 Skill 应显式声明。4.risk含义Skill 的安全风险分级是仓库安全治理的核心字段。合法值none|safe|critical|offensive|unknown分级指引如下none—— 纯文本/推理不含任何命令或状态变更safe—— 可读取文件、运行非破坏性命令critical—— 会修改状态、删除文件、推送到生产环境offensive—— 渗透测试/红队工具必须包含 Authorized Use Only仅限授权使用警告unknown—— 遗留或未分类新 Skill 应优先使用具体等级。示例risk: safe。仓库中 skills/copywriting/SKILL.md 声明risk: none纯文案工作而会执行 git 提交推送的 skills/git-pushing/SKILL.md 声明risk: critical。5.source含义Skill 的来源归属。格式URL 或短标签。示例source: community、source: https://example.com/original。说明若你是原始作者应使用self。6.source_repo与source_typesource_repo上游外部仓库的 GitHub 标识格式为OWNER/REPO如source_repo: Dimillian/Skills当 Skill 改编或引入了外部 GitHub 仓库内容时必须使用。source_type上游仓库在 README 中归入的致谢档位取值official|community|self。official意味着该仓库必须出现在 README.md 的### Official Sources下community则对应### Community Contributorssource: self配合source_type: self是原创仓库内容的正确形态。7.date_added含义Skill 进入本仓库的日期。格式YYYY-MM-DD。示例date_added: 2026-03-06。说明校验逻辑对历史内容将此项视为建议性字段但新提交应包含。四、Frontmatter 详解可选字段一些 Skill 会携带额外的元数据--- name: my-skill-name 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该 Skill 适配的目标工具列表。license可选上游材料使用的 SPDX 许可证标识如MIT、Apache-2.0、CC-BY-4.0。声明它表示许可证已验证省略则向下游工具传达许可证未验证。license_source可选上游许可证文件的直接 URL配合license供自动化工具核验若上游仓库没有 LICENSE 文件则应省略。来源致谢契约Source-credit contract英文母本规范 docs/contributors/skill-anatomy.md 对来源致谢提出了明确的硬性约定源自外部 GitHub 的 Skill 应同时声明source_repo与source_typesource_type: official的仓库必须出现在 README 的### Official Sources下community则必须出现在### Community Contributors下source: selfsource_type: self是原创内容的正确形态PR 的 CI 会检查变更 Skill 的 README 致谢覆盖情况一旦声明了source_repo缺失或错误分桶的仓库致谢会阻断 PR 合并。五、内容部分推荐的八个章节frontmatter 之后是 Skill 的实际内容。规范推荐按以下章节组织1. 标题H1# 技能标题使用清晰、有描述性的标题通常与 Skill 名称一致或在其基础上展开。2. 概述Overview## 概述 简要说明这个 Skill 做什么、为什么存在。 2~4 句话最佳。3. 何时使用When to Use## 何时使用此 Skill - 当你需要 [场景 1] 时使用 - 当处理 [场景 2] 时使用 - 当用户询问 [场景 3] 时使用为什么重要帮助 AI 判断何时激活该 Skill是触发机制的灵魂。4. 核心指令Core Instructions## 工作原理 ### 步骤 1[动作] 详细指令…… ### 步骤 2[动作] 更多指令……这是 Skill 的心脏——清晰、可执行的分步指令。仓库中 skills/git-pushing/SKILL.md 的 Safety Gates 与 Workflow 章节就是优秀范例它明确列出安全门禁先执行git status --short --branch检查、不吸收无关脏文件、受保护分支拒绝重试以及带参数的调用方式。5. 示例Examples## 示例 ### 示例 1[用例] javascript // 示例代码示例 2[另一个用例]// 更多代码**为什么示例重要**它们向 AI 精确展示好的输出长什么样。 ### 6. 最佳实践Best Practices markdown ## 最佳实践 - ✅ 应该这样做 - ✅ 也应该这样做 - ❌ 不要这样做 - ❌ 避免这样做7. 常见陷阱Common Pitfalls## 常见陷阱 - **问题**错误描述 **解决方案**如何修复8. 安全与安全提示Security Safety Notes英文母本规范还针对命令/网络/攻击类 Skill 增加了第 8 节要求当 Skill 包含 shell 命令或命令式示例、远程拉取/安装或令牌使用指引、文件变更/破坏性操作或特权操作时必须在收尾前增加专门的 Security Safety Notes 章节说明安全/不安全范围、所需的确认或授权以及必要的放行白名单注释如!-- security-allowlist: ... --。这一点在越南语版中被省略但仓库规范中属于推荐结构的一部分。9. 相关技能Related Skills## 相关技能 - other-skill - 何时改用该技能 - complementary-skill - 这些技能如何协同工作六、编写有效指令的三条铁律1. 使用清晰、直接的语言❌ 差You might want to consider possibly checking if the user has authentication.你或许可以考虑也许检查一下用户是否已认证✅ 好Check if the user is authenticated before proceeding.继续前先检查用户是否已认证2. 使用行动动词❌ 差The file should be created...文件应该被创建……✅ 好Create the file...创建文件……3. 具体化拒绝含糊❌ 差Set up the database properly.正确设置数据库✅ 好1. 创建一个 PostgreSQL 数据库 2. 运行迁移npm run migrate 3. 填充初始数据npm run seed七、可选组件scripts / examples / templates / referencesScripts 目录当 Skill 需要辅助脚本时scripts/ ├── setup.sh ← 安装自动化 ├── validate.py ← 校验工具 └── generate.js ← 代码生成器在 SKILL.md 中引用它们bash scripts/setup.shskills/git-pushing/SKILL.md 正是这样调用其scripts/smart_commit.sh助手的——它在隔离的临时索引中构建并校验提交、拒绝--空路径、仅在父提交未变时原子更新分支展示了脚本 SKILL.md 引用的成熟配合模式。Examples 目录真实世界的示例可展示 Skill 的能力边界examples/ ├── basic-usage.js ├── advanced-pattern.ts └── full-implementation/ ├── index.js └── config.jsonTemplates 目录可复用的代码模板templates/ ├── component.tsx ├── test.spec.ts └── config.json在 SKILL.md 中引用模板支持{{#include}}类语法{{#include templates/component.tsx}}References 目录外部文档或 API 参考references/ ├── api-docs.md ├── best-practices.md └── troubleshooting.md八、Skill 规模分级指南规范按内容量与章节覆盖度将 Skill 分为三档遵循先小后大、按反馈扩展的经验法则级别Frontmatter内容量章节最小可用Minimum Viable标准字段name、description、category、risk、source、date_added100–200 词概述 指令标准Standard同上300–800 词概述 何时使用 指令 示例全面Comprehensive标准字段 外部 GitHub 衍生 Skill 的source_repo/source_type 按需的可选字段800–2000 词全部推荐章节 脚本/示例/模板九、格式最佳实践代码块始终指定语言javascript、bash、typescript等便于高亮与 AI 解析。列表保持格式一致嵌套用缩进- 项目 1 - 项目 2 - 子项目 2.1 - 子项目 2.2强调重要术语用粗体一般强调用斜体命令或代码用行内代码。链接使用标准 Markdown 链接语法链接文本。十、质量检查清单Quality Checklist提交 Skill 前请逐项自查这也是仓库 docs/contributors/quality-bar.md 质量门禁思路的直观化内容质量指令清晰、可执行示例真实且有帮助无拼写或语法错误技术准确性已核实结构Frontmatter 是合法 YAMLname与目录名一致章节逻辑组织合理标题遵循层级H1 → H2 → H3完整性概述解释了为什么指令解释了怎么做示例展示了是什么边界情况已覆盖可用性初学者可以跟着做专家觉得有用AI 能正确解析解决真实问题十一、实战拆解以 brainstorming Skill 为例规范用仓库中真实存在的 skills/brainstorming/SKILL.md 做了一次完整解剖其真实 frontmatter 为--- name: brainstorming description: Use before creative or constructive work (features, architecture, behavior). Transforms vague ideas into validated designs through disciplined reasoning and collaboration. risk: critical source: community date_added: 2026-02-27 ---frontmatter 分析✅ 名称清晰brainstorming✅ description 带有强触发语义Use before creative or constructive work并解释价值✅ 说明何时使用。正文分析其内容以# Brainstorming Ideas Into Designs开头随后是紧凑的 Overview、分阶段的过程说明如一次只问一个问题必须显式澄清或提出非功能需求假设理解锁定硬门禁给出 5–7 条理解摘要并要求确认后才能进入设计每一步都是具体、可行动的易于跟随。值得注意的是brainstorming 声明risk: critical却并不执行破坏性命令——这印证了风险分级描述的是指令的潜在影响力而非字面命令强度同时它也展示了规范中核心指令 退出条件 关键原则这类硬约束写作手法。十二、高级模式条件逻辑、渐进披露与交叉引用1. 条件逻辑Conditional Logic根据用户环境分支给出不同指令## 指令 如果用户在使用 React - 使用函数组件 - 优先使用 hooks 而非 class 组件 如果用户在使用 Vue - 使用 Composition API - 遵循 Vue 3 模式2. 渐进披露Progressive Disclosure先给常见场景的简单指引再给深度用户的复杂模式## 基础用法 [面向常见场景的简单指引] ## 高级用法 [面向高级用户的复杂模式]3. 交叉引用Cross-References把 Skill 编排成工作流链条## 相关工作流 1. 首先使用 brainstorming 进行设计 2. 然后使用 writing-plans 制定计划 3. 最后使用 test-driven-development 实现仓库中的 docs/WORKFLOWS.md 与 data/workflows.json 即是这类 Skill 间编排在数据层的落地形态。十三、如何度量一个 Skill 是否有效清晰度测试不熟悉该主题的人能否跟上是否存在含糊指令完整性测试是否覆盖 happy path是否处理边界情况错误场景是否被解决有用性测试是否解决真实问题你自己会不会用它是否节省时间或提升质量仓库从工程侧给出了更量化的答案schemas/skill-score.v1.schema.json定义了 Skill 质量评分模型——按metadata × 30% documentation × 40% security × 30%加权得到 0–100 的总分并映射为excellent(≥85)/good(≥65)/needs_improvement(≥45)/critical(45)四个标签其中 metadata 维度评估必填/可选 frontmatter 字段的完整性documentation 维度评估章节覆盖、代码示例与内容深度security 维度会因检测到危险命令模式而扣分。该 schema 同时声明评分仅供参考永不阻断 Skill 使用与轻门槛进入、持续改进的哲学一致。十四、从现有 Skill 中学习规范推荐了六份仓库内的真实样例作为不同层次的教材入门向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 —— 复杂工作流。十五、专业技巧Pro Tips从何时使用章节开始写——它厘清了 Skill 的定位先写示例——示例帮你真正理解自己正在传授什么用 AI 实测——提交前验证它是否真的有效获取反馈——请他人审阅你的 Skill持续迭代——Skill 会随使用反馈不断变好。十六、要避免的常见错误❌ 错误 1过于含糊## 指令 让代码变得更好。✅ 修正## 指令 1. 将重复逻辑提取为函数 2. 为边界情况添加错误处理 3. 为核心功能编写单元测试❌ 错误 2过于复杂## 指令 [5000 字密集术语堆砌]✅ 修正拆分为多个 Skill或使用渐进披露。❌ 错误 3没有示例## 指令 [没有任何代码示例的指令]✅ 修正至少补充 2–3 个真实示例。❌ 错误 4信息过时使用 React class components……✅ 修正始终让 Skill 保持与当前最佳实践同步。十七、从仓库看 Skill 如何被索引与校验写完的 Skill 并不会孤立存在——本仓库用一套自动化链路把 frontmatter 变成可发现、可校验的资产这是理解为何 frontmatter 字段如此重要的最佳佐证索引 Schema 强制字段schemas/skills-index.v1.schema.json规定目录清单中的每个条目必须包含id、path须匹配^skills/、category、name、description、risk、source、date_added——与 frontmatter 必填字段一一对应这解释了为什么name必须匹配目录名、为什么category/risk必须显式声明。生成产物可查仓库根目录的 skills_index.json 与 data/skills_index.json 就是由各 Skill 的 frontmatter 聚合生成的真实索引每个条目都携带id、path、category、risk、source、date_added部分条目还带tags与plugin.targets如codex/claude支持标记。风险分级贯穿全链路schemas/skill-score.v1.schema.json中risk的枚举[none,safe,critical,offensive,unknown]与 frontmatter 取值完全一致且安全扣分项以SEC###模式码如 SEC002标记危险命令配合 scripts/validate-links.sh、scripts/validate-glossary.sh 等校验脚本构成编写 → 校验 → 索引 → 评分的闭环。十八、下一步行动通读 3–5 个现有 Skill观察不同风格与详略取舍套用 Skill 模板见 docs/contributors/skill-template.md入口在 docs/SKILL_TEMPLATE.md与贡献指南 docs/CONTRIBUTING.md为你的专长领域创建一个简单 Skill从最小可用档起步用 AI 助手实测它是否按预期触发与执行通过 Pull Request 分享并确保按来源致谢契约声明source_repo/source_type避免 PR 被 CI 阻断。记住每一位专家都曾是初学者。从简单开始从反馈中学习随时间持续改进。【免费下载链接】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），仅供参考
