别光会用 Skill，不会写等于白搭：从规范到原理，手把手教你给 AI Agent 造技能

一个Skill文件夹的基本结构：

skill-name/
├── SKILL.md           # 必须文件：一定要包含 元数据+指令
├── scripts/           # 可选文件: 可执行代码脚本，如：Python、Bash和JavaScript
├── references/        # 可选文件: 文档，如：详细技术参考、详细的规则文档
├── assets/            # 可选文件: 模板 , 资源，如：文档模板、配置模板、图示、示例
└── ...                # 可添加其余文件夹/文件

SKILL.md 格式规范

SKILL.md 文件必须严格遵循 YAML Frontmatter（元数据） + Markdown Body（正文） 的结构。

元数据

字段	是否必需	描述与规范
name	必需	技能的唯一标识符，必须和Skill文件夹名称一致！。通常使用小写字母和连字符（如 `pdf-form-filler`）。最多64个字符。仅限小写字母、数字和连字符。不得以连字符开头或结尾。
description	必需	核心中的核心。用 1-2 句话描述技能的功能、适用场景和触发条件。AI 仅凭此判断是否加载技能。最多1024字符。非空的。
version	可选	版本号（如 `1.0.0`），用于管理迭代。
author	可选	作者或团队名称。
allowed-tools	可选	定义技能可自动使用的工具列表（如 `Bash`, `Read`），无需用户每次确认。
license	可选	许可证名称或捆绑许可文件的引用。（开源协议、商用协议等）
metadata	可选	任意键值映射以获取额外元数据。
compatibility	可选	最多500字符。描述这个Skill需要什么环境条件。如：docker xx 版本、python 3.11+

简略的例子：

SKILL.md

yaml 复制代码

---
name: skill-name
description: A description of what this skill does and when to use it.
---

yaml 复制代码

---
name: meeting-auditor
description: 用于分析商务会议录音文本，提取关键决策，并根据合规手册审计预算风险。当用户要求"检查会议记录合规性"或"总结会议并审计"时触发。
version: 1.0.0
---

带有可选字段的示例：

SKILL.md

yaml 复制代码

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
compatibility: Requires Python 3.14+ and uv
metadata:
  author: example-org
  version: "1.0"
---

正文指令

在 Markdown 正文中，你需要从以下几个方面来构建 AI 的"思维链"和"行动指南"：

1. 角色定义 (Role Definition)

明确告诉 AI 它现在的身份。

描述方面：赋予 AI 一个具体的专家人设。
示例："你是一名严谨的财务审计员"或"你是一名资深的 Python 代码审查专家"。

2. 核心指令与步骤 (Instructions & Steps)

这是文档的主体，必须使用祈使句（命令式语气），清晰、分步骤地描述操作流程。

描述方面：
- 任务拆解：将复杂任务分解为步骤 1、2、3。
- 逻辑判断：告诉 AI 在不同情况下该如何选择（例如："如果 PDF 有密码，先调用解密脚本；如果没有，直接读取"）。
- 工具调用 ：明确指示何时运行 scripts/ 中的脚本或查阅 references/ 中的文档。

3. 输出规范 (Output Format)

规定 AI 最终呈现给用户的内容格式。

描述方面：
- 结构：例如"必须包含：摘要、风险点、建议措施三个部分"。
- 风格：例如"使用表格展示数据对比"或"代码块必须包含注释"。

4. 示例 (Examples)

提供"少样本学习"（Few-Shot Prompting）的案例，帮助 AI 理解意图。

描述方面：
- 输入/输出对：展示一个用户提问的例子，以及你期望的标准回答格式。
- 触发词示例：明确列出哪些用户语句会触发此技能（如"帮我打包这个项目"）。

5. 资源引用 (References & Assets)

指导 AI 如何使用技能包内的外部文件。

描述方面：
- 何时读取 ：例如"在执行审计前，必须先阅读 references/compliance_rules.md"。
- 如何使用 ：例如"使用 assets/template.pptx 作为生成报告的模板"。

SKILL模板

yaml 复制代码

---
name: [技能标识名]
description: [一句话描述功能 + 触发场景 + 核心价值]
version: 1.0.0
---

# [技能名称]

## 角色定义
你是一名 [具体角色]，擅长 [核心能力]。

## 核心指令
请严格按照以下步骤执行任务：
1. **分析意图**：[步骤说明]
2. **查阅资料**：如果需要，读取 `references/[文件名]` 获取详细信息。
3. **执行操作**：运行 `scripts/[脚本名]` 处理数据。
4. **输出结果**：按照下方的输出格式要求生成回答。

## 输出格式
- 必须包含：[要素 A]、[要素 B]
- 风格：[专业/幽默/简洁]

## 示例
**用户输入**：[示例提问]
**你的回答**：[示例回答]

## 错误处理
如果遇到 [某种错误]，请 [执行某种操作]。

三、创建SKILL

手动创建SKILL

创建SKILL文件夹并取名xxx-xxx （如：testcase-creator）

创建SKILL.md文件

写元数据【name必须和文件夹名称一致】

yaml 复制代码

---
name: testcase-creator
description: 根据prd需求文档，从专业的软件测试工程师角度进行分析，并生成测试用例
---

写正文指令（案例如下 ↓ ）

markdown 复制代码

# 指令:
  你是一个项目周报生成助手。你的任务是从多种数据源收集本周的项目进展，并生成结构化的周报。

## 核心流程

1. **收集数据**
    - 询问用户本周的时间范围（默认：本周一到周日）
    - 读取项目 git log，提取本周的提交记录
    - 检查是否有 issue 或 todo 文件，提取相关进展
    - 检查项目目录中是否有 problems.md/json、growth.md/json、knowledge.md/json 文件
    - 如果项目中没有上述文件，询问用户是否有额外需要添加的内容

2. **处理数据**
    - 使用 scripts/git-analyzer.py 分析 git 提交，提取关键信息
    - 使用 scripts/todo-parser.py 解析 todo/issue，整理完成情况
    - 使用 scripts/user-content-parser.py 解析项目中的用户内容文件（problems、growth、knowledge）
    - 使用 scripts/data-aggregator.py 聚合所有数据，支持 --project-dir 参数指定项目目录
    - 参考 references/data-extraction.md 了解详细的数据提取方法

3. **组织周报结构**
    - 参考 references/report-structure.md 了解周报的标准结构
    - 将数据组织成以下模块：
    - 数据统计（提交数、参与人数、完成事项等）
    - 本周进展（功能开发、问题修复、技术改进）
    - 本周遇到的问题
    - 本周个人成长
    - 相关知识分享
    - 下周计划
    - 风险与问题

4. **生成报告**
    - 参考 references/template-filling.md 了解模板填充逻辑
    - 使用 assets/report-template.html 作为模板
    - 将结构化数据填充到模板中
    - 生成 HTML 格式的周报文件：weekly-report-YYYY-MM-DD.html
    - 使用 scripts/html-to-pdf.py 将 HTML 转换为 PDF
    - 生成 PDF 格式的周报文件：weekly-report-YYYY-MM-DD.pdf

## 周报内容说明

用户需要提供以下内容（支持三种方式）：

**方式一：在项目中提供文件（推荐）**
- **本周遇到的问题**：在项目根目录创建 `problems.md` 或 `problems.json` 文件
- **本周个人成长**：在项目根目录创建 `growth.md` 或 `growth.json` 文件
- **相关知识分享**：在项目根目录创建 `knowledge.md` 或 `knowledge.json` 文件

JSON 格式需符合 user-input.json 中的结构定义。Markdown 格式需包含相应的标题和内容。

**方式二：通过 user-input.json 文件提供**
- 在 user-input.json 中定义 problems、growth、knowledge 字段

**方式三：对话提供**
- 如果项目中没有提供文件，按规则询问用户输入

内容说明：
- **本周遇到的问题**：开发过程中遇到的技术难题、阻塞问题等，包含问题描述、类型、解决方案、经验教训
- **本周个人成长**：学到的技术、能力提升、经验总结，包含类别、内容、影响
- **相关知识分享**：值得记录的技术知识点、最佳实践、学习资源，包含标题、内容、资源链接

## 使用说明

用户可以直接说："帮我生成本周的周报"，或者提供具体的时间范围。

## 注意事项

- 如果项目不是 git 仓库，跳过 git log 分析
- 如果没有 issue 或 todo 文件，提醒用户手动输入关键进展
- 需要安装 Chrome 或使用浏览器手动生成 PDF
- 同时输出 HTML 和 PDF 两种格式

创建资源文件夹，放入资源（如：references、scripts、assets等）到SKILL文件夹testcase-creator下

自动创建SKILL

这里的自动创建是指，让AI根据Anthropic 官方创建SKILL用的SKILL.md 创建我们想要的SKILL

引入Anthropic官方创建SKILL用的SKILL.md
1. 进入Anthropic官方网站：github.com/anthropics/...
2. 下载skills/skill-creator) 文件
3. 将skill-creator文件夹移到AI的SKILL文件夹下，让agent获得这个SKILL（不知道如何移动，参考下面应用SKILL）
使用skill-creator创建想要的SKILL
1. 在agent输入框内输入：/skill-creator 使用这个创建一个SKILL，需求是：xxxxx

四、应用SKILL

全局应用

全局应用是指：将这个SKILL安装到agent自身的SKILLS文件夹下。

作用范围：全局作用，只要使用这个agent，就有这个SKILL。

准备好一个SKILL文件夹（如前面创建的 testcase-creator ）
下载一个agent到本地电脑（如：opencode、cursor 等）
打开agent的SKILLS文件夹
1. 不同agent的SKILLS文件夹位置不同
把SKILL文件夹，放入到agent的SKILLS文件夹下
重新启动agent，就会加载这个SKILL了

项目应用

项目应用是指：将SKILL安装到当前项目的SKILLS文件夹下。

作用范围：项目作用，只有当前项目下启动的agent才有这个SKILL能力。

准备好一个SKILL文件夹（如前面创建的 testcase-creator ）
下载一个agent到本地电脑（如：opencode、cursor 等），下面以 opencode 为例
创建一个项目demo1
1. 在demo1目录下，创建文件夹.opencode
2. 在文件夹.opencode下创建文件夹skills
  
  为什么是.opencode，参考下面的注意事项
3. 把testcase-creator文件夹放入到文件夹skills 下
在项目目录下重新启动agent，就会加载这个SKILL了

就是在demo1文件夹下，进入命令行，输入opencode，就会重新启动项目级的agent了

注意事项： 不同agent的项目目录创建方式如下 ↓

五、SKILL原理：渐进式披露

"渐进式披露"其实是 Agent Skill 背后的核心设计哲学，是一种让AI模拟人类专家"思维效率"的认知架构。

可以将其理解为 "按需加载的专家心智" 。

想象一下，一位资深律师的大脑里储存着海量的法律知识。但在日常聊天时，她不会主动背诵《民法典》全文；只有当您咨询一个具体的合同纠纷时，她才会瞬间调动相关的法条、判例和诉讼策略，组成一个针对您问题的"临时专家思维模块什么这个"调动"而非"全盘托出"的过程，就是渐进式披露。

skill 的结构&组成

在 Agent Skills 的技术实现中，这一理念被精妙地映射为三层动态加载机制 ，而这三层结构协同实现的，正是一个完整的"认知接管"链路：

元数据层，是"识别与触发"

这是Skill对外曝露的"特征信号"，用于被 Agent 的意图识别系统扫描和匹配。当用户表达意图时，Agent 并非搜索"工具"，而是在进行领域识别，将所有 Skills 的"名片"（名称和一句话描述）载入记忆。

这就像律师记住了自己擅长"合同审查"、"知识产权"和"婚姻法"几个领域标签。成本极低，但建立了全局认知地图。

指令层，是"思考与规划"

一旦匹配，加载的核心指令，并非机械步骤，而是 "专业思维框架"的注入 。它重新规划了 Agent 的思考路径，将通用的问题解决模式，切换为领域专家的 SOP。此刻，Agent 的"思维"被临时重塑，从"我该如何回答"转变为 "按照本领域最佳实践，我应遵循如下流程" 。

skill中的详细步骤、规则与最佳实践，这是程序性知识的载体。它一旦被加载，就重新规划了Agent解决当前问题的思维链条，定义了"先想什么，后做什么，如何判断"。

这好比律师判断此事属于"合同审查"范畴后，在脑中激活了审查合同的完整 SOP：先看主体条款，再看违约责任，接着是争议解决方式...... 此时，专业的思维框架才被完整注入。

资源层，是"执行与校验"

通过调用脚本和文档，保障思维导图的高效、准确执行而配备的快速反射弧（脚本处理确定性环节）和外部记忆体（参考资料提供关键依据）。

当指令推进到需要计算、格式化或核查关键规范时，自动调用脚本（确定性执行）或读取参考（事实核查），确保了专家思维的输出，既具备灵活性，又保有确定性。