Agent Skill 入门与写作指南

Skill 入门文档

本文档介绍什么是 Skill、如何使用 Skill，以及如何写好 Skill。
内容为通用概念与写作实践，不依赖特定产品；具体工具中的路径、命令和扩展功能请查阅该产品的文档。
Skill 遵循 Agent Skills 开放标准，可被多种 AI 编程与协作工具识别与加载。

一、什么是 Skill

Skill（Agent Skill）是一种轻量、开放的格式，用于用专门知识与工作流扩展 AI Agent 的能力。
本质上，一个 Skill 就是一个包含 SKILL.md 的目录：该文件包含元数据（至少 name 和 description）以及指导 Agent 完成特定任务的说明；目录中还可以附带脚本、模板和参考材料。
在支持 Skill 的 AI 工具中，它会作为可复用、可共享的指令集存在。

• 形式：以 SKILL.md 为核心，可包含 scripts/、references/、assets/ 等可选目录（见后文）。
• 作用：让 Agent 在对话中自动或按需应用你定义的规则，例如：
  • 把工作日报转成月报并填好指定字段
  • 按团队规范生成 commit 信息
  • 按既定清单做代码审查
  • 按模板生成某种报告或文档
• 存放位置（因工具而异，常见有两种）：
  • 个人/全局：如 ~/.config/.../skills/<skill-name>/，对所有项目生效
  • 项目/仓库：如 <project>/.skills/<skill-name>/ 或 skills/<skill-name>/，仅当前仓库可用，可随代码共享

每个 Skill 通过 name 和 description 被识别：Agent 会根据当前对话与 description 的匹配程度决定是否启用；若工具支持，用户也可通过斜杠命令或菜单直接调用。

为什么需要 Skill？

Agent 能力越来越强，但往往缺少可靠完成实际工作所需的上下文。Skill 通过提供可按需加载的流程性知识和团队/公司/用户专属上下文来解决这一问题。

• 技能作者：一次编写，可在多种支持 Skill 的 Agent 产品中复用。
• 兼容的 Agent：支持 Skill 后，用户可以直接为 Agent 扩展新能力。
• 团队与组织：把组织知识沉淀为可版本管理、可携带的技能包。

更多背景见 Agent Skills 概述。

二、如何使用 Skill

2.0 Skill 如何工作（渐进式披露）

支持 Skill 的 Agent 通常采用渐进式披露来节省上下文、提高效率（参见 What are skills?）：

1. 发现（Discovery）：启动时只加载每个技能的 name 和 description，仅用于判断何时可能相关。
2. 激活（Activation）：当任务与某个技能的 description 匹配时，Agent 才把该技能的完整 SKILL.md 读入上下文。
3. 执行（Execution）：Agent 按说明执行，必要时再加载所引用的文件或运行附带脚本。

这样 Agent 既能快速判断该用哪个技能，又能在需要时获得完整说明与资源。

2.1 自动匹配

在对话里输入与某个 Skill 相关的需求时，AI 会参考该 Skill 的 description 判断是否适用。
例如：你粘贴了日报并说「帮我把这些转成月报」，若 description 里包含「日报」「月报」「任务名称」「TOP达成结果」等词，就更容易触发「日报转月报」这类 Skill。

建议：在提问时用上 Skill 会关心的关键词，便于自动匹配。

2.2 手动调用

若希望本次对话一定使用某个 Skill，可以：

• 斜杠命令（若工具支持）：输入如 /skill-name 或 /skill-name 参数内容，直接加载该技能并可选传入参数。
• 在对话中明确提及：例如「按日报转月报的 skill 来整理」「用某某 skill 的规则」。

具体入口（斜杠、命令面板、设置页等）以你使用的工具为准。

2.3 查看已有 Skill

Skill 通常以目录形式存放，每个技能一个目录，内含 SKILL.md。在你使用的工具文档中可查到「技能目录」的路径（个人 vs 项目）。列出该目录下的子目录即可看到当前可用的技能名称。

三、怎样写好 Skill

以下为与工具无关的通用写作建议，适用于遵循 Agent Skills 标准或类似约定的 Skill。

3.1 先想清楚两件事

• 做什么（WHAT）：这个 Skill 要完成哪一类具体任务。
• 什么时候用（WHEN）：用户在什么场景、说什么话时会用到。

把这两点写进 description，并加上用户可能用的触发词，AI 才能稳定地识别你的 Skill。

3.2 写好 description（最重要）

description 是 AI 是否选用该 Skill 的主要依据：

• 用第三人称写（描述「这个 Skill 能做什么」），不要写「我可以帮你……」。
• 同时写清 WHAT 和 WHEN，并带上触发词（用户可能提到的词）。
• 示例：
  「将工作日报（可有/无日期）转成月报，产出 TOP 指标与文化考评。当用户粘贴日报内容并需要 任务名称、目标值、TOP达成结果、规律总结、改进方向 时使用。」

3.3 前置元数据（YAML frontmatter）

SKILL.md 必须以 YAML frontmatter 开头（用 --- 包裹），后接 Markdown 正文。根据 Agent Skills 规范：

必填字段

name 合规示例：pdf-processing、data-analysis、code-review。
不合规：PDF-Processing（大写）、-pdf（以连字符开头）、pdf--processing（连续连字符）。

可选字段（规范中定义，具体工具可能部分支持）：

---
name: pdf-processing
description: 从 PDF 提取文本与表格，填写表单，合并文档。当用户处理 PDF 或提到 PDF、表单、文档提取时使用。
license: Apache-2.0                    # 可选：许可证名称或捆绑的许可证文件
compatibility: 需要 Python 3.9+、pdfplumber   # 可选，≤500 字符：环境/产品/依赖要求
metadata:                               # 可选：任意键值，供客户端扩展用
  author: example-org
  version: "1.0"
# 以下为部分工具扩展字段（以各产品文档为准）：
# disable-model-invocation: true
# user-invocable: false
# argument-hint: [文件名] [格式]
# allowed-tools: Bash(git:*) Read      # 实验性：预批准可用的工具
---

• description：应同时写清做什么和何时用，并包含用户/任务可能提到的触发词。规范中的好例子：“Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.” 反面例子：“Helps with PDFs.” 过于笼统。

正文：frontmatter 之后的 Markdown 正文即技能说明，无格式限制。规范建议包含：分步说明、输入/输出示例、常见边界情况。Skill 格式的优势包括：自解释（人类可读、易审计与改进）、可扩展（从纯文本到脚本与资源）、可携带（纯文件，易编辑、版本管理与分享）。

简单示例

下面是一个完整的 SKILL.md 示例（用类比与图示解释代码），涵盖前置元数据与正文说明：

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

3.4 结构清晰：流程 + 约束

• 流程：先做什么、再做什么，用 1、2、3 步骤写清楚。
• 约束：必须/禁止怎么做（如「必须基于全部日报」「某字段必填」）。
• 可加「错误做法 vs 正确做法」，减少 AI 跑偏。

3.5 给出输出模板

若产出需要填表单、写报告、写 commit，直接给一段可复用的 Markdown 模板（占位用 [ ] 或示例）。AI 会按模板填空，用户复制粘贴即可使用。

3.6 支持文件与渐进式披露

主文件 SKILL.md 建议控制在 500 行以内（规范建议正文约 5000 tokens 以内）。细节放到同目录下的可选目录中，在正文里按需引用。推荐的目录结构如下（与 Agent Skills 规范 一致）：

my-skill/
├── SKILL.md           # 必需：说明与元数据
├── scripts/           # 可选：可执行脚本
├── references/        # 可选：参考文档
└── assets/            # 可选：模板、静态资源

可选目录说明（规范建议）：

• scripts/：Agent 可执行的代码。脚本应自包含或明确写明依赖，包含清晰错误信息并妥善处理边界情况。支持的语言取决于具体实现（常见如 Python、Bash、JavaScript）。
• references/：Agent 按需阅读的文档，例如 REFERENCE.md、FORMS.md 或领域文件（如 finance.md）。单文件保持聚焦，便于按需加载、节省上下文。
• assets/：静态资源——模板（文档/配置模板）、图片（示意图、示例）、数据文件（查找表、schema）等。

渐进式披露（规范建议的上下文使用方式）：

1. 元数据（约 100 tokens）：所有技能的 name + description 在启动时加载。
2. 说明（建议 <5000 tokens）：仅在技能被激活时加载完整 SKILL.md 正文。
3. 资源（按需）：scripts/、references/、assets/ 中的文件仅在需要时加载。

引用其他文件：在 Skill 内引用其他文件时，使用相对于技能根目录的相对路径，并尽量保持一层引用（从 SKILL.md 直接链到目标文件），避免深层嵌套链。例如：

## 补充资源
- 详见 [references/REFERENCE.md](references/REFERENCE.md)
- 运行提取脚本：`scripts/extract.py`

只写 Agent 不知道或容易搞错的内容（如你们团队的字段、格式、优先级）；默认 Agent 已具备通用能力，不必解释基础概念。

3.7 命名与用词统一

• Skill 目录 / name：规范要求 name 必须与父目录名一致；小写 + 连字符，见名知意，如 daily-to-monthly-report、commit-message-helper。避免 helper、utils 等过于笼统的名称。
• 正文：同一概念只用一种说法（如统一用「日报」或「日小结」），避免混用。

3.8 常见模式

• 模板模式：在 Skill 里给出固定的输出结构（标题、段落、列表），让 AI 按模板填空。
• 示例模式：对格式要求高的场景（如 commit message），给出 2～3 个「输入 → 输出」示例。
• 工作流模式：把复杂操作拆成带勾选清单的步骤，每步写清「做什么、用什么命令/脚本」。
• 校验循环：若质量要求高，可要求「先执行脚本校验，失败则修正后再校验」，避免一次生成就结束。

3.9 建议避免的写法

• 路径：使用正斜杠，如 scripts/helper.py，避免反斜杠（与跨平台一致）。
• 选项过多：优先给一个默认做法，必要时再写「例外情况用……」。
• 时间敏感信息：避免「在 2025 年 8 月前用旧 API」这类会过期的描述；可改为「当前方法」+「已废弃方法」小节。
• 术语混用：同一概念用一种说法（如统一用「API 端点」或「路由」）。

3.10 写完后自检

• 别人只看 description，能否判断「我该在什么场景用这个 Skill」？
• 按步骤执行一遍，是否有步骤含糊或缺失？
• 是否把 AI 已会的基础知识写了一大段（可删）？
• 输出是否有模板或示例格式？
• 容易出错的地方是否写成了「必须/禁止」的硬约束？
• SKILL.md 是否在 500 行以内？过长的内容是否挪到 references/ 或 assets/？

校验：可使用 skills-ref 参考库校验技能格式（如 skills-ref validate ./my-skill），检查 frontmatter 与命名是否符合规范。具体用法见该仓库说明。

四、参考与延伸

Skill 平台与市场

除自行编写与组织内共享外，也可从以下 Skill 平台发现、获取或分发技能：

官方文档与资源

• Agent Skills 概述：为什么需要 Skill、能带来什么、采用情况与开源开发。
• What are skills?：Skill 概念、如何工作（发现/激活/执行）、SKILL.md 结构简介。
• Specification：完整格式规范（目录结构、frontmatter 必填/可选字段、name/description 约束、可选目录、渐进式披露、文件引用、校验）。
• Example skills（GitHub）：示例技能仓库。
• skills-ref：校验技能并生成 prompt XML 的参考库。
• 具体工具文档：各产品会说明技能目录路径、斜杠命令、以及该产品特有的元数据与能力（如动态上下文、子代理、权限等），在对应文档中查阅即可。