增加skill设计文档

document/specification.md

@@ -0,0 +1,238 @@
+# 规范说明
+
+> Agent Skills 的完整格式规范。
+
+本文档定义了 Agent Skills 格式规范。
+
+## 目录结构
+
+一个技能是一个目录，至少包含一个 `SKILL.md` 文件：
+
+```
+skill-name/
+└── SKILL.md          # 必需
+```
+
+<Tip>
+  你可以选择性地包含[额外的目录](#可选目录)，如 `scripts/`、`references/` 和 `assets/` 来支持你的技能。
+</Tip>
+
+## SKILL.md 格式
+
+`SKILL.md` 文件必须包含 YAML 前置数据（frontmatter），后跟 Markdown 内容。
+
+### 前置数据（必需）
+
+```yaml
+---
+name: skill-name
+description: A description of what this skill does and when to use it.
+---
+```
+
+包含可选字段：
+
+```yaml
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill forms, merge documents.
+license: Apache-2.0
+metadata:
+  author: example-org
+  version: '1.0'
+---
+```
+
+| 字段            | 是否必需 | 约束条件                                                             |
+| --------------- | -------- | -------------------------------------------------------------------- |
+| `name`          | 是       | 最多 64 个字符。仅限小写字母、数字和连字符。不能以连字符开头或结尾。 |
+| `description`   | 是       | 最多 1024 个字符。非空。描述该技能的作用以及何时使用它。             |
+| `license`       | 否       | 许可证名称或对打包许可证文件的引用。                                 |
+| `compatibility` | 否       | 最多 500 个字符。指示环境要求（目标产品、系统包、网络访问等）。      |
+| `metadata`      | 否       | 用于附加元数据的任意键值映射。                                       |
+| `allowed-tools` | 否       | 技能可能使用的预先批准工具的空格分隔列表。（实验性）                 |
+
+#### `name` 字段
+
+必需的 `name` 字段：
+
+- 必须为 1-64 个字符
+- 仅可包含 unicode 小写字母数字字符和连字符（`a-z` 和 `-`）
+- 不能以 `-` 开头或结尾
+- 不能包含连续的连字符（`--`）
+- 必须与父目录名称匹配
+
+有效示例：
+
+```yaml
+name: pdf-processing
+```
+
+```yaml
+name: data-analysis
+```
+
+```yaml
+name: code-review
+```
+
+无效示例：
+
+```yaml
+name: PDF-Processing # 不允许大写字母
+```
+
+```yaml
+name: -pdf # 不能以连字符开头
+```
+
+```yaml
+name: pdf--processing # 不允许连续的连字符
+```
+
+#### `description` 字段
+
+必需的 `description` 字段：
+
+- 必须为 1-1024 个字符
+- 应该描述该技能的作用以及何时使用它
+- 应该包含有助于代理识别相关任务的特定关键字
+
+好的示例：
+
+```yaml
+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.
+```
+
+差的示例：
+
+```yaml
+description: Helps with PDFs.
+```
+
+#### `license` 字段
+
+可选的 `license` 字段：
+
+- 指定应用于该技能的许可证
+- 我们建议保持简短（要么是许可证名称，要么是打包许可证文件的名称）
+
+示例：
+
+```yaml
+license: Proprietary. LICENSE.txt has complete terms
+```
+
+#### `compatibility` 字段
+
+可选的 `compatibility` 字段：
+
+- 如果提供，必须为 1-500 个字符
+- 仅在你的技能具有特定环境要求时才应包含
+- 可以指示目标产品、所需的系统包、网络访问需求等
+
+示例：
+
+```yaml
+compatibility: Designed for Claude Code (or similar products)
+```
+
+```yaml
+compatibility: Requires git, docker, jq, and access to the internet
+```
+
+<Note>
+  大多数技能不需要 `compatibility` 字段。
+</Note>
+
+#### `metadata` 字段
+
+可选的 `metadata` 字段：
+
+- 从字符串键到字符串值的映射
+- 客户端可以使用它来存储未由 Agent Skills 规范定义的附加属性
+- 我们建议使你的键名足够唯一以避免意外冲突
+
+示例：
+
+```yaml
+metadata:
+  author: example-org
+  version: '1.0'
+```
+
+#### `allowed-tools` 字段
+
+可选的 `allowed-tools` 字段：
+
+- 预先批准运行的工具的空格分隔列表
+- 实验性功能。不同代理实现对该字段的支持可能有所不同
+
+示例：
+
+```yaml
+allowed-tools: Bash(git:*) Bash(jq:*) Read
+```
+
+### 正文内容
+
+前置数据后的 Markdown 正文包含技能指令。没有格式限制。编写任何有助于代理有效执行任务的内容。
+
+推荐的部分：
+
+- 分步指令
+- 输入和输出示例
+- 常见边界情况
+
+请注意，代理在决定激活技能后将加载整个文件。考虑将较长的 `SKILL.md` 内容拆分为引用文件。
+
+## 可选目录
+
+### scripts/
+
+包含代理可以运行的可执行代码。脚本应该：
+
+- 自包含或清楚地记录依赖关系
+- 包含有用的错误消息
+- 优雅地处理边界情况
+
+支持的语言取决于代理实现。常见选项包括 Python、Bash 和 JavaScript。
+
+### references/
+
+包含代理可以在需要时阅读的附加文档：
+
+- `REFERENCE.md` - 详细的技术参考
+- `FORMS.md` - 表单模板或结构化数据格式
+- 特定于领域的文件（`finance.md`、`legal.md` 等）
+
+保持单个[参考文件](#文件引用)专注。代理按需加载这些文件，因此较小的文件意味着更少的上下文使用。
+
+### assets/
+
+包含静态资源：
+
+- 模板（文档模板、配置模板）
+- 图像（图表、示例）
+- 数据文件（查找表、模式）
+
+## 渐进式披露
+
+技能的结构应高效利用上下文：
+
+1. **元数据**（~100 tokens）：所有技能在启动时加载 `name` 和 `description` 字段
+2. **指令**（建议 < 5000 tokens）：技能激活时加载完整的 `SKILL.md` 正文
+3. **资源**（按需）：文件（例如 `scripts/`、`references/` 或 `assets/` 中的文件）仅在需要时加载
+
+将主 `SKILL.md` 保持在 500 行以下。将详细参考资料移动到单独的文件中。
+
+## 文件引用
+
+在技能中引用其他文件时，使用从技能根目录开始的相对路径：
+
+```markdown
+Run the extraction script:
+scripts/extract.py
+```
+
+保持文件引用从 `SKILL.md` 开始只有一层深度。避免深度嵌套的引用链。

document/what-are-skills.md

@@ -0,0 +1,65 @@
+# 什么是技能？
+
+> Agent Skills 是一种轻量级、开放的格式，用于通过专业知识和工作流扩展 AI 代理的能力。
+
+核心来说，一个技能是一个包含 `SKILL.md` 文件的文件夹。该文件包含元数据（至少包括 `name` 和 `description`）以及告诉代理如何执行特定任务的指令。技能还可以打包脚本、模板和参考资料。
+
+```directory theme={null}
+my-skill/
+├── SKILL.md          # 必需：指令 + 元数据
+├── scripts/          # 可选：可执行代码
+├── references/       # 可选：文档
+└── assets/           # 可选：模板、资源
+```
+
+## 技能如何工作
+
+技能使用**渐进式披露**来高效管理上下文：
+
+1. **发现**：在启动时，代理仅加载每个可用技能的名称和描述，足以了解何时可能相关。
+
+2. **激活**：当任务匹配技能的描述时，代理将完整的 `SKILL.md` 指令读入上下文。
+
+3. **执行**：代理遵循指令，根据需要可选择性地加载引用文件或执行打包的代码。
+
+这种方法使代理保持快速，同时能够按需访问更多上下文。
+
+## SKILL.md 文件
+
+每个技能都从包含 YAML 前置数据和 Markdown 指令的 `SKILL.md` 文件开始：
+
+```mdx
+---
+name: pdf-processing
+description: Extract text and tables from PDF files, fill forms, merge documents.
+---
+
+# PDF Processing
+
+## When to use this skill
+
+Use this skill when the user needs to work with PDF files...
+
+## How to extract text
+
+1. Use pdfplumber for text extraction...
+
+## How to fill forms
+
+...
+```
+
+以下前置数据在 `SKILL.md` 的顶部是必需的：
+
+- `name`：简短标识符
+- `description`：何时使用此技能
+
+Markdown 正文包含实际指令，对结构或内容没有特定限制。
+
+这种简单格式具有一些关键优势：
+
+- **自文档化**：技能作者或用户可以阅读 `SKILL.md` 并了解其功能，使技能易于审核和改进。
+
+- **可扩展**：技能的复杂度可以范围从仅文本指令到可执行代码、资产和模板。
+
+- **可移植**：技能只是文件，因此易于编辑、版本控制和共享。