如何去创建一个规范化的Agent SKIll？

背景介绍

随着现阶段agent的发展，其功能也越来越强大，agent skill的使用也越发频繁，这篇文章教大家如何去编写一个多平台agent兼容的skill

什么是skill

简单来说，是一个包含SKILL.md的文件夹，agent通过读取SKILL.md来规范化进行某些特定任务

一个好的 Skill 应该符合哪些规范

1. 轻量化

Agent 上下文是共有的，skill 内部的说明步骤可以清晰，但没必要太过详细。

好的示例（约 50 tokens）

提取 PDF 文本

使用 pdfplumber 提取文本：
python 复制代码
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

反面教材（300+ tokens）

PDF（Portable Document Format）文件是一种常见的文件格式... 首先需要使用 pip 安装库...然后可以使用下面的代码...

2.合适的自由度

根据任务的可变性选择指令的具体程度

高自由度（文本指令）：多种方法都有效，依赖上下文判断
中等自由度（伪代码+参数）：存在首选模式，但允许变化
低自由度（具体脚本）：操作脆弱易错，必须严格遵守顺序

3.渐进式披露

将内容分层，避免一次性加载过多内容，导致上下文占满

text 复制代码

pdf-skill/
├── SKILL.md              # 主指令（触发时加载）
├── FORMS.md              # 表单填写指南（按需加载）
├── reference.md          # API 参考（按需加载）
└── scripts/
    ├── analyze_form.py   # 执行，不加载到上下文
    └── fill_form.py

核心原理

Agent 分三个阶段加载内容：

启动时：只加载所有 skill 的 name + description（约 100 tokens）
激活时：读取完整的 SKILL.md（约 1000-2000 tokens）
执行时：按需读取 reference 文件（1000-3000 tokens）

SKILL.md 文件格式

必须章节 5个

1. 必要的YAML Frontmatter(SKILL.md 开头位置)

yaml 复制代码

---
name: skill-name              # 必需，1-64字符，小写+连字符
description: 技能描述和使用场景  # 必需，1-1024字符
license: Apache-2.0           # 可选
compatibility: 环境要求        # 可选
metadata:                     # 可选
  author: example-org
  version: "1.0"
---

`name` 字段规则

1-64 字符
只能包含小写字母、数字和连字符
不能以连字符开头或结尾
不能包含连续连字符
推荐使用动名词形式 （如 processing-pdfs）

`description` 字段最佳实践

必须包含两部分：

技能做什么
何时使用

makefile 复制代码

好的示例：
description: 从 PDF 文件中提取文本和表格，填充表单，合并文档。
当处理 PDF 文件或用户提及 PDF、表单、文档提取时使用。

坏的示例：
description: 帮助处理文档

2. 快速开始

bash 复制代码

## 快速开始

最常用的 1-2 个命令/操作示例
让用户/skill-name 能立即上手

作用：

给出最简单的使用方式
1-3 个代码示例

3.领域索引

shell 复制代码

##  领域索引 / 规范索引

列出所有 reference 文件及其适用场景

作用：

导航中心，告诉 agent 有哪些领域
每个领域简短描述（1-2 句话）
说明何时使用每个领域
提供 reference 文件链接

4.标准工作流

makefile 复制代码

## 标准工作流

分步骤说明完整流程
step1:...
step2:...

作用：

告诉 agent 做事的顺序
何时读哪个 reference 文件
关键决策点

5.重要规范

shell 复制代码

## 重要规则

适用于所有场景的关键规则

作用：

强调必须遵守的规则
常见错误的预防
约 200-500 tokens

重点：始终使用第三人称，避免"我可以..."或"你可以..."

文件组织形式

这里推荐一种通用性强的组织方式，基本上90%的skill都能以该格式进行组织

领域分离模式

bash 复制代码

skill-name/
├── SKILL.md              # 导航中心（必需）
├── scripts/              # 可执行脚本（可选）
│   ├── script1.py
│   └── script2.sh
├── references/           # 领域知识库（推荐）
│   ├── domain1.md
│   ├── domain2.md
│   └── domain3.md
└── assets/               # 静态资源（可选）
    ├── templates/
    └── schemas/

在这种结构中，SKILL.md的主要职责是：

快速概览：让 agent 知道这个 skill 能做什么
领域索引：列出所有领域及其入口
路由指引：告诉 agent 不同场景读哪个文件
基础指令：提供最常用的通用操作

但是不应该包含具体的细节知识，以及过多的代码样例

简化版（小型 skill）

如果你的 skill 内容较少（< 500 行），可以只用一个 SKILL.md：

bash 复制代码

simple-skill/
└── SKILL.md              # 所有内容都在这里

实战示例：git commit 规范化Skill

文件结构

bash 复制代码

git-commit-standard/
├── SKILL.md                          # 导航中心 (~1000 tokens)
├── scripts/
│   ├── analyze_diff.py              # 分析 git diff
│   ├── generate_commit.py           # 生成提交信息
│   └── validate_commit.py           # 验证提交格式
└── references/
    ├── conventional-commits.md      # 约定式提交规范 (~2000 tokens)
    ├── language-specific.md         # 语言特定规范 (~1800 tokens)
    ├── project-types.md             # 项目类型模板 (~1500 tokens)
    ├── chinese-commits.md           # 中文提交规范 (~1200 tokens)
    └── commit-examples.md           # 优秀示例库 (~2500 tokens)

由于篇幅原因，这里只提供skill.md,关于结构中其他文件遵循以下规则即可

文档文件：

介绍该怎么做，而不是为什么，也就是不要花大篇幅去给ai说明原理
具体，而不是抽象；使用"文件行数大于等于500行"代替"复杂文件"
不要让ai去根据具体时间去判断什么事，如果一定要，编写脚本
第三人称

脚本文件：

在skill文件中说明不要去读取具体的脚本
包含可读性强的错误日志以及过程输出
包含--help指令，让ai通过命令式交互，而不是通过读取脚本文件去推断

如果想查阅官方推荐的skill格式，可以参照：github.com/anthropics/...

SKILL.md 示例

说明：这是一个省略版的 SKILL.md 示例，展示了所有推荐章节。实际编写时，SKILL.md 应该控制在 500-1000 行（1000-2000 tokens）。

详细的规范内容（如 conventional-commits.md）应该放在 references/ 目录中。

yaml 复制代码

---
name: git-commit-standard
description: 生成符合规范的 Git 提交信息，支持约定式提交、中文提交、语言特定规范。当用户请求创建 commit、生成提交信息、或提及"git commit"、"提交代码"、"规范提交"时使用。支持 feat/fix/docs 等类型识别。
---

# Git Commit 规范化

## 快速开始

### 自动生成提交信息

```bash
# 分析当前 staged changes
python scripts/analyze_diff.py

# 生成提交信息
python scripts/generate_commit.py --style conventional
```

### 验证提交信息格式

```bash
# 验证提交信息是否符合规范
python scripts/validate_commit.py "feat(auth): add JWT authentication"
```

---

## 📚 规范索引（Standard Index）

根据用户需求和项目类型选择对应的规范文档：

### 1. 约定式提交（Conventional Commits）
- **适用场景**：开源项目、团队协作、自动化发版
- **关键元素**：type(scope): description、BREAKING CHANGE
- **示例**：`feat(api): add user login endpoint`
- **详细文档**：[references/conventional-commits.md](references/conventional-commits.md)

### 2. 语言特定规范
- **适用场景**：特定语言生态的项目（Swift/iOS、Java/Android、Python、Go 等）
- **涵盖内容**：语言社区约定、框架特定规范、工具链要求
...



---

## 🔍 快速查找

不确定使用哪个规范时，使用 grep 搜索关键词：

```bash
# 搜索特定类型
grep -i "feat|feature" references/*.md

# 搜索特定场景
grep -i "重构|refactor" references/*.md
grep -i "breaking change" references/*.md

# 搜索语言
grep -i "swift|ios" references/*.md
grep -i "python" references/*.md
```

---

## 📋 标准工作流

### 第 1 步：确定项目规范
```bash
# 检查项目是否有 commit 规范配置
ls .commitlintrc* commitlint.config.* .gitmessage 2>/dev/null

# 查看最近的提交风格
git log --oneline -20
```

### 第 2 步：选择规范文档

根据项目情况选择：

| 项目特征 | 选择规范 |
|---------|---------|
| 有 `.commitlintrc` 配置 | conventional-commits.md |
| go 项目 | language-specific.md（GO部分） |
| 中文团队 | chinese-commits.md |
| 开源项目 | conventional-commits.md |
| 看最近 commit 风格 | 模仿现有风格，参考 commit-examples.md |

### 第 3 步：分析变更内容

```bash
# 查看 staged 变更
git diff --cached

# 使用脚本自动分析
python scripts/analyze_diff.py
```

脚本会输出：
```json
{
  "files_changed": ["src/auth/login.swift", "tests/auth_tests.swift"],
  ...
}
```

### 第 4 步：生成提交信息

根据规范类型生成：

```bash
# 约定式提交（英文）
python scripts/generate_commit.py --style conventional

# 中文提交
...
```

### 第 5 步：验证和提交

```bash
# 验证格式
python scripts/validate_commit.py "$(git log -1 --pretty=%B)"

# 如果验证通过，推送
git push
```

---

## 🎯 常见场景

### 场景 1：新功能开发

1. 阅读 [references/conventional-commits.md](references/conventional-commits.md) 的 feat 类型
2. 确定 scope（影响的模块）
3. 编写清晰的描述
4. 如有 BREAKING CHANGE，添加到 footer

```bash
feat(auth): add JWT token refresh mechanism

- Implement automatic token refresh before expiration
- Add retry logic for failed refresh attempts
- Update authentication middleware

BREAKING CHANGE: AuthService.login() now returns Promise<AuthResult> instead of User
```

### 场景 2：Bug 修复

...
```

---

## ⚙️ 脚本详解

### analyze_diff.py

**功能**：分析 git diff，智能推断 commit 类型和 scope

```bash
python scripts/analyze_diff.py [--cached] [--format json|text]
```

**输出示例**：
```json
{
 ...
}
```

### generate_commit.py

**功能**：基于分析结果生成规范的 commit message

...

---

## ⚠️ 重要规则

### 1. Type 必须小写

```bash
✅ feat(auth): add login
❌ Feat(auth): add login
❌ FEAT(auth): add login
```

### 2. 描述使用祈使句

```bash
✅ feat: add user authentication
❌ feat: added user authentication
❌ feat: adds user authentication
```

### 3. 首字母小写（英文规范）

```bash
✅ fix(api): resolve timeout issue
❌ fix(api): Resolve timeout issue
```

### 4. 不要用句号结尾

```bash
✅ docs: update README
❌ docs: update README.
```

### 5. Body 和 Footer 用空行分隔

```bash
feat(auth): add OAuth support

This commit implements OAuth 2.0 authentication
with support for Google and GitHub providers.

BREAKING CHANGE: AuthConfig interface changed
Closes #123
```

---

## 📊 Commit Type 参考表

| Type | 含义 | 何时使用 | 影响版本 |
|------|------|---------|---------|
| `feat` | 新功能 | 添加新的功能特性 | MINOR |
| `fix` | Bug 修复 | 修复线上或测试发现的 bug | PATCH |
...

详细说明见 [references/conventional-commits.md](references/conventional-commits.md)


---

## 📖 使用示例

### 示例 1：iOS 项目新功能

```bash
# 1. 查看变更
git diff --cached

# 2. 确定这是 iOS 项目，阅读语言特定规范
cat references/language-specific.md | grep -A 20 "Swift/iOS"

# 3. 生成提交
python scripts/generate_commit.py --style swift

# 输出建议：
# feat(auth): add biometric authentication support
#
# - Implement Face ID and Touch ID
# - Add fallback to passcode
# - Update security documentation
```

### 示例 2：中文团队修复 Bug

```bash
# 1. 阅读中文提交规范
cat references/chinese-commits.md

# 2. 手动编写提交
git commit -m "fix(支付): 修复订阅续费重复扣款问题

- 添加幂等性密钥防止重复扣款
- 实现事务锁机制
- 完善错误日志

Fixes #1234"
```

### 示例 3：开源项目重大变更

```bash
# 1. 阅读约定式提交规范
cat references/conventional-commits.md | grep -A 30 "BREAKING CHANGE"

# 2. 提交
git commit -m "feat(api)!: redesign authentication API

Redesign the authentication API to support multiple
identity providers and improve security.

BREAKING CHANGE: AuthService.login() signature changed
- Old: login(username: string, password: string)
- New: login(credentials: AuthCredentials)

Migration guide available in docs/migration-v2.md

Refs: #456, #789"
```

---

## ✅ 检查清单

提交前确认：

- [ ] 选择了正确的 commit type
- [ ] scope 准确反映了变更范围
- [ ] 描述简洁清晰（< 72 字符）
...

---

## 🎓 最佳实践

### 1. 原子提交

每个 commit 只做一件事：

```bash
✅ 好的做法：
commit 1: feat(auth): add login API
commit 2: feat(auth): add logout API
commit 3: test(auth): add auth integration tests

❌ 坏的做法：
commit 1: feat: add auth stuff
```

### 2. 频繁提交

小步快跑，便于回滚和 review：

```bash
✅ 每完成一个小功能就提交
❌ 一天工作结束后一次性提交所有改动
```

### 3. 有意义的描述

```bash
✅ fix(api): resolve race condition in concurrent requests
❌ fix: bug fix
❌ fix: various fixes
```

如何去创建一个规范化的Agent SKIll？

背景介绍

什么是skill

一个好的 Skill 应该符合哪些规范

1. 轻量化

好的示例（约 50 tokens）

反面教材（300+ tokens）

2.合适的自由度

3.渐进式披露

核心原理

SKILL.md 文件格式

1. 必要的YAML Frontmatter(SKILL.md 开头位置)

name 字段规则

description 字段最佳实践

2. 快速开始

作用：

3.领域索引

作用：

4.标准工作流

作用：

5.重要规范

作用：

文件组织形式

领域分离模式

简化版（小型 skill）

实战示例：git commit 规范化Skill

文件结构

文档文件：

脚本文件：

SKILL.md 示例

`name` 字段规则

`description` 字段最佳实践