Appearance
Skill规范定义指南：从结构到安全自检清单
Skill 不是插件，是给 AI 的操作说明书。一份写得好的 Skill，让 AI 知道什么时候用、怎么用、输出什么格式。
一、Skill 到底是什么
很多人第一反应觉得 Skill 是某种插件——装完之后有个程序在后台跑。实际上完全不是。
Skill 更像是给 AI 的一份操作说明书。你在 SKILL.md 里写清楚：什么时候用这个技能、用的时候按什么步骤走、输出什么格式。AI 读到这份说明，就知道遇到对应情况该怎么处理。
更严格的定义是：
Skill = 可发现的元数据 + 可执行/可操作的过程性指令 + 可选资源（references/assets/scripts）+ 渐进式加载策略 +（可选）权限/环境门控
简单说，Skill 是一个以文件夹为单位的、可复用的 AI 能力包。
二、标准文件结构
一个规范的 Skill 目录结构如下：
my-skill/
├── SKILL.md # 核心文件，必须有
├── references/ # 可选：补充知识/规范文档
│ └── reference.md
├── assets/ # 可选：模板/静态资源
│ └── template.md
└── scripts/ # 可选：可执行脚本
└── run.sh关键规则：
SKILL.md必须直接放在skills/your-skill-name/目录下- 不能再嵌套一层，
skills/my-skill/src/SKILL.md这种结构是错的 - 目录名建议与 Skill 名称保持一致，全小写，用连字符分隔
三、SKILL.md 的标准写法
SKILL.md 分为两部分：YAML frontmatter（元数据）和 Markdown 正文（指令）。
3.1 元数据区（frontmatter）
yaml
---
name: trend-scout
description: |
当用户询问某个话题的最新趋势、热点动态、行业动向时使用。
适用场景：科技行业趋势、社交媒体热点、市场情报收集。
不适用于：历史事件查询、个人建议、代码生成。
version: 1.0.0
author: your-name
requires:
- web-search
- summarize
platforms:
- macos
- linux
---元数据字段说明：
| 字段 | 是否必填 | 说明 |
|---|---|---|
| name | ✅ 必填 | 与目录名保持一致 |
| description | ✅ 必填 | AI 用来判断是否调用此 Skill 的核心依据 |
| version | 推荐 | 便于审计与回滚 |
| author | 推荐 | 便于溯源 |
| requires | 按需 | 声明依赖的其他 Skill 或工具 |
| platforms | 按需 | 限定运行平台，避免跨平台报错 |
3.2 正文区（Instructions）
正文是 Skill 的核心，描述 AI 执行时的具体步骤。推荐使用三段式结构：
markdown
## 触发条件
明确说明什么情况下使用这个 Skill，以及什么情况下不应该使用。
## 执行步骤
1. 第一步：做什么
2. 第二步：做什么
3. 第三步：做什么
## 输出格式
定义最终输出的结构、格式、语言风格等要求。完整示例：
yaml
---
name: daily-brief
description: |
当用户说"生成今日简报"、"给我每日摘要"或"今天有什么重要消息"时使用。
不适用于查询特定话题的历史记录。
version: 1.2.0
author: your-name
---
## 触发条件
用户请求生成当日信息摘要时激活。
## 执行步骤
1. 获取今日日期与天气信息
2. 搜索今日科技/行业热点（限最近24小时）
3. 拉取用户预设的关注关键词相关新闻
4. 将以上内容整合为结构化摘要
## 输出格式
用以下格式输出，不超过500字：
📅 **日期**：YYYY-MM-DD
🌤️ **天气**：[城市] [温度] [天气状况]
📌 **今日要闻**
- 要闻1（来源）
- 要闻2（来源）
💡 **值得关注**
[1-2句话的综合判断]四、description 的写法是成败关键
最佳实践：把 description 写成「可检索的触发器」，包含用户可能说的关键词，以及明确的使用边界。
❌ 错误写法（太模糊）：
帮助你更高效地完成任务✅ 正确写法（精准触发）：
当用户询问某个话题的最新趋势、热点动态、行业动向时使用。
触发词：趋势分析、热点、最新动态、行业报告。
不适用于：历史事件、代码问题、个人决策建议。写 description 的三个原则：
- 包含用户可能说的原话，不是你认为准确的术语
- 明确写出不适用场景，防止 AI 误调用
- 控制在 5 行以内，过长反而降低检索精度
五、渐进式信息披露原则
AgentSkills 规范的加载策略：启动时仅加载元数据（name/description），触发后加载 SKILL.md 正文，执行时再按需读取资源或运行脚本。
这意味着你应该：
| 位置 | 内容 |
|---|---|
| SKILL.md 正文 | 放核心流程，保持精简 |
| references/ | 放详细规范、API 文档、策略说明 |
| assets/ | 放模板、示例输出 |
| scripts/ | 放需要执行的脚本 |
不要把所有内容都堆在 SKILL.md 里，大文件会占用不必要的上下文，降低执行效率。
六、常见错误与避坑指南
写完发现 AI 不用这个 Skill，或者用错了，几个常见原因：
❌ 错误1：description 写得太模糊
AI 判断要不要用 Skill，靠的是 frontmatter 里的 description。写成「处理各种任务」这种宽泛的话，AI 不知道该不该用，通常选择不用。
❌ 错误2：文件夹结构嵌套错误
bash
# 错误：多了一层 src
skills/my-skill/src/SKILL.md ❌
# 正确
skills/my-skill/SKILL.md ✅❌ 错误3：改完没重启生效
OpenClaw 在启动时扫描 skills 目录，改完 SKILL.md 需要重启 gateway 才能生效。
❌ 错误4：元数据与实际行为不一致
常见误区：metadata 与实际行为不一致，比如声明「只读」却在脚本里执行了写操作。
❌ 错误5：硬编码敏感信息
如果要发布给他人使用，检查 SKILL.md 里是否有 API Key、服务器 IP、本地路径——这些必须替换成占位符或从环境变量读取。
七、安全规范（不可忽视）
Skills 通过指令和代码为 Claude 提供新功能，虽然这使它们功能强大，但也意味着恶意 Skill 可以指导 Claude 以与 Skill 声称的目的不匹配的方式调用工具或执行代码。
写 Skill 时的安全自检清单：
- ✅ description 与实际执行行为一致
- ✅ 无硬编码 API Key、密码、路径
- ✅ scripts/ 中的脚本逻辑透明可读
- ✅ 权限声明最小化，不索取多余权限
- ✅ 不包含任何外部数据外传逻辑
- ✅ 敏感操作有明确的用户确认步骤
八、一份完整的 Skill 模板
my-skill/
└── SKILL.mdyaml
---
name: my-skill
description: |
【一句话说清楚】当用户说 XXX 的时候使用这个 Skill。
触发词：关键词1、关键词2、关键词3。
不适用于：场景A、场景B。
version: 1.0.0
author: your-name
platforms:
- macos
- linux
---
## 使用场景
[详细描述适用和不适用的情况]
## 执行步骤
1. [第一步]
2. [第二步]
3. [第三步]
## 输出格式
[定义输出结构，包括格式、长度、语气]
## 注意事项
- [执行时需要注意的边界条件]
- [错误处理方式]九、总结：规范 Skill 的六个核心原则
| 原则 | 要点 |
|---|---|
| 单一职责 | 一个 Skill 只做一件事，不要贪大求全 |
| 描述精准 | description 要能让 AI 准确判断触发时机 |
| 结构清晰 | 三段式：触发条件 → 执行步骤 → 输出格式 |
| 渐进加载 | 核心逻辑在 SKILL.md，细节放 references |
| 安全透明 | 无敏感信息硬编码，行为与声明一致 |
| 版本管理 | 加版本号，便于回滚和审计 |
一个写得好的 Skill，最终效果是：AI 知道什么时候该用它，用的时候按你预期的方式执行，输出格式稳定可预期。达到这三点，这个 Skill 就算合格了。
关键词：Skill定义, AI技能包, SKILL.md, AgentSkills规范, Claude Code技能, 技能包开发, AI操作说明书
