Skill语法完全手册：从入门到精通让AI100%按你的规则执行 ​

AI工具调用次次错？流程教了八百遍还是忘？Skill就是你的终极解决方案！Skill是符合AgentSkills规范的可执行技能包，本质上是给AI代理用的标准化操作SOP。把流程固化成Skill，AI自动就能按标准流程执行，成功率100%。

什么是Skill？ ​

Skill是符合AgentSkills规范的可执行技能包，本质上是给AI代理用的标准化操作SOP。

不用你每次都一步步告诉AI：先搜资料、再写文件、最后发消息。把流程固化成Skill，AI自动就能按标准流程执行。

目前所有主流AI开发平台（OpenClaw、Claude Desktop、Cursor等）都已经支持Skill语法，一次编写，多平台运行。

核心设计理念：渐进式披露（Progressive Disclosure）——元数据常驻上下文，SKILL.md按需加载，脚本和引用文件只在需要时调用，高效管理有限的上下文窗口资源。

Skill文件结构与生效范围 ​

一个标准Skill就是一个独立文件夹，核心是SKILL.md文件，采用YAML Frontmatter + Markdown内容的双层结构：

---
name: skill-name
description: 技能的详细描述，AI据此判断是否触发
allowed-tools: Read, Grep, Bash
model: sonnet
---

# 技能标题
这里是技能的指令内容，Markdown格式...

完整目录结构 ​

skill-name/
├── SKILL.md          # 核心文件，必须有
├── reference.md      # 可选：参考文档
├── examples.md       # 可选：示例集合
└── scripts/          # 可选：自定义脚本
    └── run.py

生效范围与优先级 ​

YAML Frontmatter元数据语法 ​

必填字段 ​

编写技巧：description要写得"pushy"一些，明确列出触发场景的关键词，因为AI倾向于"欠触发"而非"过触发"。

可选字段 ​

allowed-tools常用值 ​

Markdown指令语法 ​

标题层级 ​

# 技能名称
## 步骤一：准备工作
### 1.1 检查环境

条件判断 ​

如果用户要求生成报告：
  - 先读取数据文件
  - 再按模板格式输出

如果用户要求发送邮件：
  - 先草拟邮件内容
  - 等待用户确认后发送

变量引用 ​

用户提到的文件：$FILE_PATH
当前日期：$CURRENT_DATE

步骤序列 ​

1. 读取用户指定的文件
2. 分析文件内容，提取关键信息
3. 按照输出模板整理结果
4. 将结果写入指定位置

输出格式定义 ​

输出格式：
- 标题：[生成的报告标题]
- 摘要：[100字以内摘要]
- 正文：[分段输出]
- 结论：[总结性陈述]

渐进式披露：管理上下文资源 ​

三层加载机制 ​

为什么这样设计 ​

• 元数据常驻：让AI知道"有这个能力可用"
• SKILL.md按需：只在触发时加载，节省上下文
• 引用文件更懒：只在执行过程中需要时才读取

示例：

my-skill/
├── SKILL.md           # 核心流程，触发时加载
├── reference.md       # API文档，执行时按需读取
├── examples.md        # 示例，生成时按需参考
└── scripts/
    └── validate.py    # 验证脚本，检查时才执行

实战：写一个完整的Skill ​

示例：代码审查Skill ​

---
name: review-code
description: 当用户要求代码审查、review代码、检查代码质量时自动触发
allowed-tools: Read, Grep, Bash(git:*)
---

# 代码审查

## 步骤

1. 用Bash执行`git diff`获取当前改动
2. 分析改动涉及的文件和模块
3. 检查以下方面：
   - 代码风格是否一致
   - 是否有明显的逻辑错误
   - 是否有安全风险
   - 测试覆盖是否充分
4. 按风险等级输出审查结果

## 输出格式

### 高风险
- [文件:行号] 问题描述

### 中风险
- [文件:行号] 问题描述

### 建议
- 改进建议

## 注意事项

- 不要审查自动生成的代码
- 不要审查第三方库的代码
- 不确定的地方标注"待确认"

最佳实践 ​

总结 ​

一句话：Skill让AI从"你告诉它怎么做"变成"它自己知道怎么做"——流程标准化，执行100%。