Agent Skill 知识速查表

本页面汇总 Agent Skill 的核心知识点，方便快速查阅。

核心概念

概念	说明
Agent Skill	可复用的 AI 能力模块，包含指令文件
SKILL.md	Skill 的核心文件，包含元数据和指令
frontmatter	YAML 格式的元数据区域
name	Skill 的唯一标识符
description	功能描述和触发条件

文件结构

最小结构

my-skill/
└── SKILL.md

完整结构

my-skill/
├── SKILL.md           # 核心文件（必需）
├── scripts/           # 可执行脚本（可选）
│   ├── analyze.py
│   └── validate.sh
├── references/        # 参考文档（可选）
│   ├── REFERENCE.md
│   └── FORMS.md
└── assets/            # 静态资源（可选）
    ├── templates/
    └── images/

渐进式披露（三层加载）

层级	内容类型	加载内容	加载时机	Token 预算
1. 元数据	frontmatter	name + description	会话启动时（所有 Skills）	~100 tokens/skill
2. 指令	SKILL.md 正文	完整指令内容	Skill 被激活时	< 5000 tokens（建议）
3. 资源	额外文件	scripts、references、assets	指令明确引用时	按需加载

SKILL.md 格式

基本模板

---
name: "skill-name"
description: "功能描述。当用户 [触发条件] 时触发。"
---

# 角色定义

你是一位专业的 [角色]。

## 核心职责

- 职责一
- 职责二

## 工作流程

### 第一步
[描述]

### 第二步
[描述]

## 输出格式

[输出模板]

Frontmatter 字段

必需字段

字段	类型	限制	示例
name	string	小写字母、数字、连字符，≤64 字符，不能以连字符开头/结尾，不能有连续连字符，必须匹配目录名	`code-reviewer`
description	string	1-1024 字符，非空，祈使语气编写，包含功能描述和触发条件	`审查代码。当用户请求代码审查时触发。`

可选字段

字段	类型	限制	说明
license	string	-	许可证名称或引用的许可证文件
compatibility	string	≤500 字符	环境要求说明
metadata	object	键值对	额外元数据属性
allowed-tools	string	空格分隔	预批准的工具列表（实验性）
disable-model-invocation	boolean	true/false	禁用自动触发，只能显式调用

完整示例

---
name: "api-doc-generator"
description: "为 REST API 生成 OpenAPI 文档。当用户需要生成 API 文档时触发。"
license: "MIT"
compatibility: "Requires Node.js 18+"
metadata:
  author: "your-name"
  version: "2.1.0"
allowed-tools: "read_file write_file"
---

name 命名规范

✅ 正确
code-reviewer
python-linter
api-doc-generator
test-writer-v2

❌ 错误
Code_Reviewer    # 大写字母和下划线
代码审查          # 非 ASCII 字符
-code-reviewer   # 以连字符开头
code-reviewer-   # 以连字符结尾
code--reviewer   # 连续连字符
a-very-long-name-exceeding-sixty-four-characters-limit  # 超长

重要：name 必须与 Skill 目录名称一致。

description 编写公式

[功能描述]。当用户 [触发条件] 时触发。

示例

description: "审查 Python 代码质量，检查 PEP 8 规范。当用户请求代码审查、代码检查、code review 或提交 Python 代码时触发。"

工具目录位置

工具	项目级目录	全局目录
Claude Code	`.claude/skills/`	`~/.claude/skills/`
OpenAI Codex	`.codex/skills/`	`~/.codex/skills/`
Trae IDE	`.trae/skills/`	`~/.trae/skills/`
Cursor	`.cursor/skills/`	`~/.cursor/skills/`
Windsurf	`.windsurf/skills/`	`~/.windsurf/skills/`
Gemini CLI	`.gemini/skills/`	`~/.gemini/skills/`
OpenCode	`.opencode/skills/`	`~/.opencode/skills/`
Cline	`.cline/skills/`	`~/.cline/skills/`

跨客户端共享：.agents/skills/ 已成为跨客户端共享 Skills 的通用约定。

指令结构模板

# 角色定义
[说明 AI 扮演的角色]

## 核心职责
[列出主要任务]

## 工作流程
### 第一步
### 第二步
### ...

## 检查清单
- [ ] 检查项一
- [ ] 检查项二

## 输出格式
[定义输出结构]

## 注意事项
[边界情况和注意事项]

设计原则

原则	说明
简洁是关键	上下文窗口是公共资源，添加 Agent 缺乏的，省略它已知道的
单一职责	每个 Skill 只做一件事，封装一致的工作单元
明确边界	定义适用范围和边界情况
精准触发	description 包含功能和触发条件，使用祈使语气编写
结构化指令	使用检查清单和示例
适当自由度	根据任务脆弱性调整指令具体程度

自由度选择

自由度	使用场景	示例
高	多种方法有效，任务可容忍变化	文本指令："分析代码结构"
中	有验证方法但需调整参数	伪代码/带参数脚本
低	操作脆弱，必须遵循特定顺序	特定脚本，不允许修改

指令模式

模式	说明	使用场景
易错点清单	列出环境特定的陷阱	API 超时、时区问题、空值处理
模板	提供输出格式模板	格式化输出必须符合特定结构
检查清单	多步骤工作流跟踪	确保不跳过步骤
验证循环	执行-验证-修复循环	确保输出质量
计划-验证-执行	先规划再执行	批量或破坏性操作

脚本设计规范

规范	说明
避免交互式提示	硬性要求，Agent 无法响应 TTY 提示
提供 --help	包含描述、可用标志、使用示例
有帮助的错误信息	说明问题、期望、建议
结构化输出	优先 JSON/CSV，数据到 stdout，诊断到 stderr
幂等性	不存在则创建，而非重复报错
Dry-run 支持	破坏性操作提供预览功能
有意义的退出码	不同失败类型使用不同退出码

从真实经验出发

Skill 的有效编写方法：

方法	说明
从实际任务提取	与 Agent 协作完成后，提取可复用模式
从项目文档综合	用内部文档、运维手册、代码审查记录等
用真实执行优化	运行后反馈所有结果，迭代改进

验证 Skill

使用 skills-ref 验证

# 验证 Skill 格式
npx skills-ref validate ./my-skill

# 验证所有 Skills
npx skills-ref validate ./**/*.skill

常见验证错误

错误	原因	解决方案
Missing required field: name	缺少 name 字段	在 frontmatter 中添加 name
Invalid name format	name 包含非法字符	只使用小写字母、数字、连字符
Name does not match directory	name 与目录名不一致	修改 name 或重命名目录
Description exceeds 1024 characters	description 太长	缩短描述内容
Description is empty	description 为空	添加有意义的描述

问题优先级

级别	符号	说明
严重	🔴	必须修复，可能导致错误
警告	🟡	建议修复，代码风格问题
建议	🔵	可选优化，改进建议

常见类型（type）

类型	说明	示例
feat	新功能	`feat: 添加用户登录`
fix	修复 bug	`fix: 修复登录问题`
docs	文档变更	`docs: 更新 README`
style	代码格式	`style: 格式化代码`
refactor	重构	`refactor: 重构用户服务`
perf	性能优化	`perf: 优化查询`
test	测试	`test: 添加登录测试`
chore	构建/工具	`chore: 更新依赖`

快速创建 Skill

步骤

创建目录：mkdir -p .trae/skills/my-skill
创建文件：touch .trae/skills/my-skill/SKILL.md
编写内容：填写 frontmatter 和指令
测试验证：使用关键词触发测试

最小示例

---
name: "hello-world"
description: "打招呼。当用户说你好或 hello 时触发。"
---

# 打招呼助手

友好地回应用户的问候。

调试清单

frontmatter 使用 --- 包围
name 字段存在且符合规范
description 字段存在且不超过 1024 字符
description 包含功能描述和触发条件
Skill 文件位于正确的目录
文件编码为 UTF-8

官方资源

资源	链接	说明
官方规范	agentskills.io	Agent Skills 开放标准官网
规范文档	Specification	完整格式规范
客户端实现	Adding Skills Support	客户端实现指南
Claude Code 文档	Skills	Claude Code 官方文档
OpenAI Codex 文档	Skills	OpenAI Codex 官方文档
GitHub 仓库	agentskills/agentskills	规范和示例代码
Anthropic Skills	anthropics/skills	Anthropic 官方 Skills 示例

命名推荐

官方推荐使用动名词形式（gerund form）命名 Skill：

✅ 推荐
processing-pdfs
analyzing-spreadsheets
managing-databases
testing-code
writing-documentation

✅ 可接受
pdf-processing, spreadsheet-analysis
process-pdfs, analyze-spreadsheets

❌ 避免
helper, utils, tools          # 太通用
documents, data, files        # 没有动作含义

评估质量

测试用例结构

组成部分	说明
提示词	真实的用户消息
预期输出	人类可读的成功描述
输入文件	Skill 需要处理的文件（可选）

好的断言特征

特征	示例
可编程验证	`"输出文件是有效的 JSON"`
具体可观察	`"条形图有标签化的坐标轴"`
可计数	`"报告包含至少 3 条建议"`

评估最佳实践

实践	说明
从小开始	2-3 个测试用例开始
变化提示词	不同措辞、详细程度、正式程度
覆盖边界	测试格式错误输入、不寻常请求
要求证据	PASS 需要具体证据
保持精简	更少更好的指令 > 详尽规则

调试清单

frontmatter 使用 --- 包围
name 字段存在且符合规范
name 与目录名一致
description 不超过 1024 字符
description 包含功能和触发条件
description 使用祈使语气
Skill 位于正确目录
文件编码为 UTF-8
使用 npx skills-ref validate 验证通过

核心概念​

文件结构​

最小结构​

完整结构​

渐进式披露（三层加载）​

SKILL.md 格式​

基本模板​

Frontmatter 字段​

必需字段​

可选字段​

完整示例​

name 命名规范​

description 编写公式​

示例​

工具目录位置​

指令结构模板​

设计原则​

自由度选择​

指令模式​

脚本设计规范​

从真实经验出发​

验证 Skill​

使用 skills-ref 验证​

常见验证错误​

问题优先级​

常见类型（type）​

快速创建 Skill​

步骤​

最小示例​

调试清单​

官方资源​

命名推荐​

评估质量​

测试用例结构​

好的断言特征​

评估最佳实践​

调试清单​

核心概念

文件结构

最小结构

完整结构

渐进式披露（三层加载）

SKILL.md 格式

基本模板

Frontmatter 字段

必需字段

可选字段

完整示例

name 命名规范

description 编写公式

示例

工具目录位置

指令结构模板

设计原则

自由度选择

指令模式

脚本设计规范

从真实经验出发

验证 Skill

使用 skills-ref 验证

常见验证错误

问题优先级

常见类型（type）

快速创建 Skill

步骤

最小示例

调试清单

官方资源

命名推荐

评估质量

测试用例结构

好的断言特征

评估最佳实践

调试清单