跳到主要内容

Agent Skill 知识速查表

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

核心概念​

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

文件结构​

最小结构​

my-skill/
└── SKILL.md

完整结构​

my-skill/
├── SKILL.md           # 核心文件（必需）
├── templates/         # 模板文件（可选）
│   └── example.md
└── config/            # 配置文件（可选）
    └── rules.json

SKILL.md 格式​

基本模板​

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

# 角色定义

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

## 核心职责

- 职责一
- 职责二

## 工作流程

### 第一步
[描述]

### 第二步
[描述]

## 输出格式

[输出模板]

Frontmatter 字段​

必需字段​

字段类型限制示例
namestring小写字母、数字、连字符，≤64 字符code-reviewer
descriptionstring≤1024 字符审查代码。当用户请求代码审查时触发。

可选字段​

字段类型说明
versionstring版本号，如 1.0.0
authorstring作者名称
tagsarray标签列表

name 命名规范​

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

❌ 错误
Code_Reviewer    # 大写字母和下划线
代码审查          # 非 ASCII 字符
a-very-long-name-exceeding-sixty-four-characters-limit  # 超长

description 编写公式​

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

示例​

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

工具目录位置​

工具项目级目录全局目录
Claude Code.claude/skills/~/.claude/skills/
Trae IDE.trae/skills/~/.trae/skills/
Cursor.cursor/skills/~/.cursor/skills/
Windsurf.windsurf/skills/~/.windsurf/skills/
Gemini CLI.gemini/skills/~/.gemini/skills/

指令结构模板​

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

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

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

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

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

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

设计原则​

原则说明
单一职责每个 Skill 只做一件事
明确边界定义适用范围和边界情况
精准触发description 包含功能和触发条件
结构化指令使用检查清单和示例

问题优先级​

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

常见类型（type）​

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

快速创建 Skill​

步骤​

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

最小示例​

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

# 打招呼助手

友好地回应用户的问候。

调试清单​

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

官方资源​