一、先搞清楚Skill到底是什么

很多人第一反应觉得Skill是某种插件，装完之后有个程序在后台跑。

实际上完全不是。

Skill更像是给AI的一份操作说明书。你在SKILL.md里写清楚：什么时候用这个技能、用的时候按什么步骤走、输出什么格式。AI读到这份说明，就知道遇到对应情况该怎么处理。

更严格的定义是：Skill等于可发现的元数据加上可执行的操作指令，再加上可选资源（比如参考资料、静态文件、脚本），再加上渐进式加载策略，再加上可选的权限和环境控制。

简单说，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 元数据区

---
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 正文区

正文是Skill的核心，描述AI执行时的具体步骤。推荐用三段式结构。

先写触发条件，明确说明什么情况下用这个Skill，什么情况下不该用。

再写执行步骤，第一步做什么，第二步做什么，第三步做什么，一步一步列清楚。

最后写输出格式，定义最终输出的结构、格式、语言风格等要求。

下面是一个完整示例：

---
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写成可检索的触发器，里面包含用户可能说的关键词，还要明确写出使用边界。

错误写法太模糊，比如帮助你更高效地完成任务。AI看了不知道什么时候该用。

正确写法要精准，比如当用户询问某个话题的最新趋势、热点动态、行业动向时使用。触发词写清楚是趋势分析、热点、最新动态、行业报告。不适用于历史事件、代码问题、个人决策建议。

写description有三个原则。第一，包含用户可能说的原话，不要用你自己觉得准确的术语。第二，明确写出不适用场景，防止AI误调用。第三，控制在5行以内，太长反而降低检索精度。

五、渐进式信息披露原则

AgentSkills规范的加载策略是这样的：启动时只加载元数据，也就是name和description。触发之后才加载SKILL.md正文。执行的时候再按需读取资源或运行脚本。

这意味着你应该这样安排内容：SKILL.md正文放核心流程，保持精简。references文件夹放详细规范、API文档、策略说明。assets文件夹放模板、示例输出。scripts文件夹放需要执行的脚本。

不要把所有的内容都堆在SKILL.md里。文件太大会占用不必要的上下文，降低执行效率。

六、常见错误和避坑指南

写完发现AI不用这个Skill，或者用错了，通常是下面几个原因。

第一个错误，description写得太模糊。AI判断要不要用Skill，靠的是frontmatter里的description。写成处理各种任务这种宽泛的话，AI不知道该不该用，一般就选择不用了。

第二个错误，文件夹结构嵌套错了。skills/my-skill/src/SKILL.md这种多了一层src的是错的。正确的应该是skills/my-skill/SKILL.md。

第三个错误，改完没有重启生效。OpenClaw在启动时扫描skills目录，改完SKILL.md需要重启gateway才能生效。

第四个错误，元数据和实际行为不一致。比如声明了只读，却在脚本里执行了写操作。

第五个错误，硬编码了敏感信息。如果要发布给他人使用，检查SKILL.md里有没有API Key、服务器IP、本地路径。这些必须替换成占位符或者从环境变量里读取。

七、安全规范

Skills通过指令和代码为Claude提供新功能。虽然这让它们功能强大，但也意味着恶意的Skill可以指导Claude做一些和声称目的不匹配的事情。

写Skill的时候要做安全自检。检查description和实际执行行为是不是一致。检查有没有硬编码的API Key、密码、路径。检查scripts文件夹里的脚本逻辑是不是透明可读的。检查权限声明是不是最小化，不要索取多余的权限。检查有没有包含任何把数据往外传的逻辑。敏感操作要有明确的用户确认步骤。

八、一份完整的Skill模板

my-skill/
└── SKILL.md

---
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就算合格了。

本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！

链接: https://fly63.com/article/detial/13609