深入剖析 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 Skills（AAS）中一个技能（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 1：Frontmatter 元数据详解

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_type；
source_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 - ❌ Don't do this - ❌ Avoid this

7. 常见陷阱（Common Pitfalls）

## Common Pitfalls - **Problem:** Description **Solution:** How to fix it

8. 安全与安全须知（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 / references

Scripts 目录

技能需要辅助脚本时，可放在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/file

Examples 目录

存放能演示技能的实战示例：

examples/ ├── basic-usage.js ├── advanced-pattern.ts └── full-implementation/ ├── index.js └── config.json

Templates 目录

存放可复用的代码模板：

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.md

skills/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_added`）	100–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 是合法 YAML
name与文件夹名一致
章节逻辑组织合理
标题层级正确（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 正确解析，再逐步扩充到综合级别。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析