哪些工具支持 SKILL.md？

Claude Code、Codex CLI、Gemini CLI、Antigravity CLI、Kiro CLI、Cursor、GitHub Copilot 等 19+ 工具。已经是事实标准。

SKILL.md 和 CLAUDE.md 有什么区别？

CLAUDE.md 每次对话都加载。SKILL.md 只在 description 匹配时才加载。专用工作流用 SKILL.md，全局规则用 CLAUDE.md。

SKILL.md body 应该写多长？

500 行以内。超过就拆成多个 skill，或者把参考资料放到 references/ 子目录。

为什么我的 skill 触发不了？

description 里没有用户实际会说的词。要写具体的触发短语和场景，不要写抽象的能力描述。

SKILL.md 写法教程：一次写好，19+ AI 编程工具通用

2026年6月12日 · 14 分钟阅读

#AI #Claude Code #Codex #教程 #Tools

SKILL.md 是什么？

SKILL.md 是 AI 编程工具的跨平台指令文件。写一个文件，Claude Code、Codex CLI、Gemini CLI、Kiro CLI、Cursor 等 19+ 工具都能识别。

过去几个月我写了 30 多个 skill——部署、测试、代码审查、内容工作流都有。模式本身不复杂，但头几次写基本都会踩同样的坑。这篇讲的就是什么真正管用。

工作原理

加载分两步：

索引阶段 — 启动时只读每个 SKILL.md 的 YAML frontmatter（name 和 description），建立轻量索引
匹配阶段 — 用户发消息时，拿消息和所有 description 做匹配。命中了才加载完整的 markdown body

所以 description 字段决定一切。写不好，skill 永远不会被触发。

文件放在哪？

路径因工具而异，但格式完全相同：

工具	个人 skill 路径	项目级 skill 路径
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex CLI	`~/.codex/skills/` 或 `~/.agents/skills/`	`.codex/skills/`
VS Code Copilot	`~/.github/skills/`	`.github/skills/`
Gemini CLI	`~/.gemini/skills/`	`.gemini/skills/`
Antigravity CLI	`~/.agy/skills/`	`.agy/skills/`
Kiro CLI	`~/.kiro/skills/`	`.kiro/skills/`

目录名就是调用命令。Claude Code 里打 /skill-name，Codex 里打 $skill-name。SKILL.md 内部格式跨平台通用。

SKILL.md 的结构

---
name: deploy-to-staging
description: "Use when the user asks to deploy, push to staging, or ship to test environment. Runs the deployment pipeline with safety checks."
---

# 部署到 Staging

## 使用场景
- 用户说「部署」「推到 staging」「上测试环境」
- 测试通过后，用户想看线上效果

## 操作步骤
1. 执行 `pnpm test`，确认所有测试通过
2. 执行 `pnpm build`，确认构建成功
3. 运行 `./scripts/deploy-staging.sh`
4. 把部署 URL 报告给用户

## 规则
- 测试没过不准部署
- 部署前必须和用户确认
- 部署失败时展示错误日志并建议修复方案

description 怎么写才能触发？

description 是成败关键。看看什么有用什么没用：

差的写法	为什么不行	好的写法
”Helps with deployments”	太模糊，匹配不到具体请求	”Use when the user asks to deploy, push to staging, or ship to test"
"Code review tool”	没有描述触发时机	”Use when reviewing PRs, checking code quality, or before merging"
"Database utilities”	没有触发词	”Use when the user asks to run migrations, seed data, or query the database”

四条规则：

用 “Use when” 开头 — 强迫你描述触发场景
包含用户实际会说的词 — 「部署」「推」「上线」，不是「启动部署序列」
列 2-3 个触发场景 — 覆盖同一意图的不同说法
200 字符以内 — 工具会截断长描述

五个写坏 skill 的方式

1. 巨型 skill

一个 SKILL.md 什么都干：部署、测试、review、写文档。

解法： 一个 skill 只干一件事。如果 description 里用了两个以上的「和」，就该拆了。

2. 把 body 写成文档

写一堆解释性的文字，而不是给命令。

<!-- 差：像文档一样 -->
部署流程涉及多个阶段，包括构建应用、
运行测试、以及推送到 staging 环境...

<!-- 好：祈使句，给指令 -->
1. 执行 `pnpm build`
2. 执行 `pnpm test`
3. 运行 `./scripts/deploy.sh`
4. 从 stdout 获取 URL 并报告

3. 没有示例

Agent 不知道好的输出长什么样。

## 示例

输入："把 auth 服务部署到 staging"

输出：
- 测试运行：47 通过，0 失败
- 构建成功（2.3s）
- 已部署到：https://staging.example.com/auth
- 健康检查：✅ 200 OK

4. Skill 之间冲突

两个 skill 的 description 有重叠。工具会随机选一个。

解法： 让 description 互斥。「Use when deploying to staging」和「Use when deploying to production」——不是泛泛的「Use when deploying」。

5. Body 超过 500 行

太长会吃掉 context window，拖慢响应。

解法： 把参考资料移到 references/ 子目录：

my-skill/
├── SKILL.md          # 核心指令（500 行以内）
└── references/
    ├── api-schema.md # 需要时才加载
    └── examples.md

可以直接抄的模板

---
name: skill-name-here
description: "Use when [触发短语 1], [触发短语 2], or [触发短语 3]. Does [产出什么]."
---

# Skill 标题

## 使用场景
- [具体场景 1]
- [具体场景 2]
- [具体场景 3]

## 操作步骤
1. [第一步——明确输入是什么]
2. [第二步——写具体命令]
3. [第三步——描述预期输出]

## 示例

输入："[用户真实会说的话]"

输出：
[Agent 应该产出什么]

## 规则
- [硬性约束 1]
- [硬性约束 2]
- [绝对不做的事]

怎么测试你的 skill？

改 description，然后看能不能触发：

# 在 Claude Code / Codex / Kiro CLI 里：
> deploy to staging

# skill 被激活了吗？看 context 面板。
# 没激活就调 description，再试。

反复调 description 直到触发可靠。这是唯一需要测试的东西。

SKILL.md 和其他配置文件的关系

文件	何时加载	用途
SKILL.md	按需（description 匹配时）	专用工作流
CLAUDE.md / AGENTS.md	每次对话	项目全局规则、风格指南
.cursorrules	每次对话（Cursor）	编辑器偏好
.env	始终	密钥、API Key

进阶：frontmatter 里的高级字段

规范在不断演进。跨平台会遇到这些字段：

字段	支持平台	作用
`disable-model-invocation`	Claude Code, VS Code Copilot	设为 `true` 阻止自动触发，只能通过 `/skill-name` 手动调用。适合有副作用的工作流。
`context: fork`	VS Code Copilot（实验性）	在独立子 Agent 上下文中运行 skill，而不是内联加载。
`dependencies`	Claude Code	声明依赖包（如 `python>=3.8, pandas>=1.5.0`），加载时自动安装。
`user-invocable`	Claude Code	设为 `false` 让 skill 只能被模型调用，不出现在 slash 命令中。

Codex 的隐式调用控制不在 SKILL.md 里，而是在单独的 agents/openai.yaml 文件中设置 policy.allow_implicit_invocation: false。

命名规则（来自 agentskills.io 规范）：

最长 64 字符
只能用小写字母、数字、连字符
必须和目录名一致
不能包含保留词（“anthropic”、“claude”）
description 最长 1024 字符（和 when_to_use 合计截断在 1536 字符）

安全注意事项

Skill 是文本指令，不是沙箱代码。要像对待依赖包一样对待它：

安装前读一遍 SKILL.md——文本文件，30 秒搞定
优先用知名仓库的 skill（github.com/anthropics/skills、github.com/openai/skills）
对 scripts/ 目录里有可执行脚本的 skill 保持警惕
用项目级 skill（.claude/skills/）而不是全局（~/.claude/skills/），限制影响范围
规范目前没有 skill 签名或信任等级——安装前先看内容