AI Skill 的编写及使用方法

文章说明：本文详细介绍 AI Agent Skills 的概念、结构、编写方法和实际使用技巧，帮助你为 AI 助手打造可复用的专业能力。

一、什么是 AI Skill？

1.1 核心概念

AI Skill（技能） 是一组打包好的指令和资源，教会 AI 如何专业地完成某类特定任务。

📌 简单理解：Skills 就是给 AI 的"岗位培训手册"。没有 Skills，AI 只能聊天；有了 Skills，AI 能专业做事。

1.2 Skills vs 普通 Prompt

对比项	普通 Prompt	Skills 机制
复用方式	每次重新描述	一次编写，反复调用
上下文占用	每次全量塞入	渐进式加载（按需读取）
一致性	依赖每次 prompt 质量	高（固定 SOP+ 模板）
维护成本	改一次要重新发	修改文件，全局生效

1.3 Skills vs MCP vs Tools

很多人容易混淆这三个概念：

Skills = 岗位培训大礼包（PDF+SOP+ 模板 + 话术）—— 用于知识复用
MCP = 给 AI 装了一套专业软件 —— 用于能力扩展
Tools = 给 AI 一把锤子 —— 用于单一功能调用

二、Skill 的核心结构

2.1 最小结构

一个 Skill 最简只需要一个文件夹 + 一个文件：

my-skill/
└── SKILL.md    # 唯一必需文件

2.2 完整结构

复杂 Skill 可以包含更多资源：

my-skill/
├── SKILL.md          # 核心指令 + 元数据（必需）
├── scripts/          # 可执行代码（可选）
├── references/       # 参考资料库（可选）
├── templates/        # 模板文件（可选）
└── assets/           # 其他资源（可选）

2.3 SKILL.md 文件格式

SKILL.md 由两部分组成：YAML Frontmatter + Markdown 正文

---
name: skill-name              # 必填：技能标识
description: >-               # 必填：功能描述
  详细说明该 Skill 的功能和使用场景
version: "1.0"                # 可选：版本号
author: your-name             # 可选：作者
trigger_keywords:             # 可选：触发关键词
  - 关键词 1
  - 关键词 2
---

# 正文开始（Markdown 格式）

这里是给 AI 的具体指令...

2.4 字段说明

字段	必需	说明	限制
`name`	✅	技能标识，也是 slash 命令名	≤64 字符，小写 + 数字 + `-`
`description`	✅	功能描述，AI 靠它匹配任务	≤1024 字符
`version`	❌	版本号	-
`author`	❌	作者信息	-
`trigger_keywords`	❌	触发关键词列表	大幅提升自动触发率

三、编写第一个 Skill

3.1 场景：代码注释专家

让我们创建一个 Skill，让 AI 成为专业的代码注释专家。

3.2 创建目录

# 个人全局 Skills（所有项目可用）
mkdir -p ~/.claude/skills/code-comment-expert

# 或项目级 Skills（仅当前项目可用）
mkdir -p ./.claude/skills/code-comment-expert

3.3 编写 SKILL.md

---
name: code-comment-expert
description: >-
  为代码添加专业、清晰的中英双语注释。
  适合缺少文档、可读性差、需要分享审查的代码。
trigger_keywords:
  - 加注释
  - 注释
  - 加文档
  - explain code
  - document
---

# 代码注释专家

你现在是「专业代码注释专家」。

## 核心原则

1. **只在必要处添加**：缺少注释或可读性明显不足的地方
2. **双语注释**：优先使用英文 JSDoc/TSDoc 风格
3. **精炼简洁**：每行注释不超过 80 字符
4. **绝不修改逻辑**：只添加注释，不改变原有代码行为

## 输出格式

1. 先输出完整修改后的代码块
2. 再用 diff 形式展示改动部分
3. 最后说明加了哪些注释、理由

四、实战：让 AI 帮你自动写 Skill

💡 小技巧：其实你不需要手写 Skill！把你的操作步骤告诉 AI，它能帮你生成完整的 SKILL.md 文件。下面是真实案例。

4.1 场景：我想让 AI 自动写日报

假设我每天下班前都要写日报，格式固定但内容每天不一样。我想让 AI 根据我的工作记录自动生成日报。

4.2 给 AI 的提示词

我是这样跟 AI 说的：

我想创建一个 Skill，让 AI 帮我自动写工作日报。

【我的需求】
1. 我每天会零散记录一些工作内容（比如"修复了登录 bug"、"开了项目评审会"）
2. 下班前 AI 帮我把这些内容整理成正式日报
3. 日报格式要符合我们公司的模板

【日报格式】
## 今日工作
1. 【已完成】xxx（具体成果 + 数据）
2. 【进行中】xxx（当前进度 + 下一步计划）

## 问题与风险
- 需要协调的事项
- 可能的延期风险

## 明日计划
1. xxx
2. xxx

【示例输入】
- 上午修复了登录页面的验证码 bug
- 下午参加了 Q2 项目评审会，定了 5 月份上线
- 还在搞性能优化，目前 FPS 从 30 提升到 45，目标是 60

【示例输出】
## 今日工作
1. 【已完成】修复登录页面验证码 bug，解决用户反馈的登录失败问题
2. 【进行中】性能优化专项，FPS 从 30 提升至 45（目标 60），预计下周完成

## 问题与风险
- Q2 项目 5 月份上线，需要前端组配合联调

## 明日计划
1. 继续性能优化，目标 FPS 达到 60
2. 准备 Q2 项目联调环境

请帮我创建一个 Skill，包含完整的 SKILL.md 文件，让我以后只要说"写日报"就能自动触发。

4.3 AI 生成的 Skill

AI 听完我的描述，生成了这样的 SKILL.md：

---
name: daily-report-generator
description: >-
  根据用户零散的工作记录自动生成格式化的工作日报。
  适合需要每日汇报工作进展的职场人士。
  常见触发场景：写日报、生成日报、今日工作总结、daily report
trigger_keywords:
  - 写日报
  - 生成日报
  - 今日工作总结
  - 日报
  - daily report
version: "1.0"
author: AI Assistant
---

# 工作日报生成器

你是一个专业的工作日报助手，擅长将零散的工作记录整理成结构化、专业化的日报。

## 核心原则

1. **成果导向**：把"做了什么"改成"达成了什么成果"
2. **数据支撑**：有数字的一定要保留并突出
3. **风险前置**：主动识别可能的问题和延期风险
4. **语言精炼**：每条不超过 2 行，避免啰嗦

## 处理流程

1. 提取用户输入中的所有工作项
2. 分类为【已完成】或【进行中】
3. 补充必要的上下文（如果用户没说清楚，可以合理推断）
4. 识别需要协调的事项和潜在风险
5. 根据已完成/进行中的工作，推断明日计划
6. 按公司模板格式输出

## 输出格式（严格遵守）

```markdown
## 今日工作
1. 【已完成】xxx（具体成果 + 数据）
2. 【进行中】xxx（当前进度 + 下一步计划）

## 问题与风险
- 需要协调的事项
- 可能的延期风险

## 明日计划
1. xxx
2. xxx
```

## 注意事项

- 如果用户输入太简单（比如只有 1 条记录），主动询问是否需要补充
- 不要编造用户没提过的内容，不确定的用"待确认"标注
- 语气保持专业但不过于正式，适合在钉钉/企业微信群发送

## 示例

### 用户输入
- 上午修复了登录页面的验证码 bug
- 下午参加了 Q2 项目评审会，定了 5 月份上线
- 还在搞性能优化，目前 FPS 从 30 提升到 45，目标是 60

### 输出
## 今日工作
1. 【已完成】修复登录页面验证码 bug，解决用户反馈的登录失败问题
2. 【进行中】性能优化专项，FPS 从 30 提升至 45（目标 60），预计下周完成

## 问题与风险
- Q2 项目 5 月份上线，需要前端组配合联调

## 明日计划
1. 继续性能优化，目标 FPS 达到 60
2. 准备 Q2 项目联调环境

4.4 使用效果

创建完这个 Skill 后，我每天下班前只需要：

# 直接跟 AI 说
写日报
- 修复了支付页面的金额显示 bug
- 跟产品确认了下周需求
- 性能测试报告还没写完，完成 70%

# AI 自动生成
## 今日工作
1. 【已完成】修复支付页面金额显示 bug，避免用户支付金额错误
2. 【已完成】与产品确认下周需求，明确开发优先级
3. 【进行中】性能测试报告，完成 70%，预计明天提交

## 问题与风险
- 无

## 明日计划
1. 完成性能测试报告并提交
2. 开始下周需求的开发准备

💡 经验总结：

让 AI 写 Skill 时，示例最重要，一定要给输入输出示例
把格式要求说清楚，AI 才知道怎么组织内容
生成后可以再让 AI 优化，比如"加一个检查错别字的功能"

五、进阶 Skill 编写技巧

4.1 渐进式加载

Skills 的核心优势是渐进式加载——只在需要时才读取完整内容，节省 Token。

在 SKILL.md 中引用其他文件：

## 参考模板

需要给出标准函数组件时，参考 `templates/functional.tsx.md` 的结构。

## 遵守规范

如果违反 Hooks 规则，对照 `references/hooks-rules.md` 第 3-5 条说明。

4.2 添加示例文件

在 examples/ 目录下存放优秀/反面示例：

examples/
├── good-example.md      # 优秀示例
└── anti-pattern.md      # 反面教材

4.3 添加可执行脚本

在 scripts/ 目录下存放自动化脚本：

# scripts/validate-props.py
import sys
import re

def validate_props(code):
    pattern = r'props\.([a-z_]+)'
    matches = re.findall(pattern, code)
    invalid = [m for m in matches if not m.startswith('_')]
    if invalid:
        print(f"警告：发现未规范的 props: {invalid}")
        return False
    return True

if __name__ == "__main__":
    code = sys.argv[1]
    sys.exit(0 if validate_props(code) else 1)

六、Skill 存放位置与加载顺序

6.1 存放位置

平台	个人全局路径	项目级路径
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Cursor	`~/.cursor/skills/`	`.cursor/skills/`
Moltbot	`~/.moltbot/skills/`	`./skills/`

6.2 加载优先级

企业级（管理控制台配置）
项目级（当前项目）
个人级（~/.claude/skills/）
共享级（配置文件中指定的额外目录）

七、最佳实践

7.1 命名规范

✅ 推荐：code-comment-expert, pdf-processor, react-review
❌ 避免：CodeCommentExpert, pdf_processor, my skill

规则：小写字母 + 数字 + 连字符，不以连字符开头或结尾。

7.2 Description 编写技巧

Description 是 AI 判断是否加载 Skill 的关键，要：

包含触发场景：说明什么情况下使用
使用自然语言：像人类描述任务一样
覆盖同义词：包含多种表达方式

6.3 控制 Skill 大小

核心指令控制在 400-800 行
复杂内容拆分到 references/
模板和示例放在单独目录按需加载

七、总结

核心要点回顾

Skills 是什么：可复用的 AI 能力扩展包
核心结构：SKILL.md + 可选资源目录
关键优势：渐进式加载，Token 效率高
编写要点：清晰的 description + 具体的指令 + 必要的示例

下一步行动

从简单 Skill 开始（如代码注释、格式转换）
逐步添加资源和脚本
分享你的 Skills 到社区
探索多 Skill 协作的复杂工作流