Appearance
Skill设计技巧大全：100例核心原则与最佳实践
一个Skill专注完成一项任务。Description是触发器，写给机器看要精准。
什么是Skill？
Skill包（技能包）是一种标准化的AI能力模块：
- 本质：包含SKILL.md核心文件的文件夹
- 功能：将特定任务的SOP、知识、脚本、资源封装为可复用、可组合、可自动触发的单元
- 定位：AI Agent的专项操作手册 + 执行工具包
特点：纯文件、无服务、按需加载、跨平台、可组合
一、Skill核心设计原则（9条）
原则1：单一、分层、清晰、明确、灵活、复用、工程化
| 要素 | 说明 |
|---|---|
| 单一职责 | 一个Skill专注完成一项任务 |
| 资源分层加载 | 元数据→指令→脚本/参考/资源（按需加载） |
| 清晰触发 | description精准描述何时调用 |
| 步骤明确 | 指令分步、可执行、无歧义 |
| 确定性脚本 | 重复/计算逻辑放入scripts/，避免AI出错 |
| 确定性与灵活性分离 | 精确操作→scripts/；判断生成→SKILL.md |
| 可复用、可测试 | 示例+模板+脚本，独立验证、随处复用 |
| 工程化规范 | 统一命名、目录结构、版本管理 |
原则2：单一职责优先
推荐做法：
router-skill → 判断用户意图，派给对应的专家
order-status-skill → 只管订单查询
return-skill → 只管退货
product-qa-skill → 只管产品咨询效果：准确率从62%提升到90%
错误做法：
创建一个大而全的"万能Skill"，试图一网打尽所有功能。
原则6：一致性原则
一个Skill里保持一致的命名、格式、规范、术语。
命名规范：
| 有效名称 | 无效名称 |
|---|---|
| git-release | Git-Release（大写） |
| docker-build | git_release（下划线） |
| pr-review | git release（空格） |
| test-123 | -git-release（以短横线开头） |
原则7：安全性原则
必须考虑安全性，防止恶意输入或意外操作：
- 使用bash时防止命令注入
- 实施最小权限原则
- 对敏感操作进行用户确认
零信任架构核心：永不信任，始终验证
原则8：性能优化原则
| 手段 | 效果 |
|---|---|
| 提示词压缩 | Token用量减少60% |
| 智能路由 | 成本降低58% |
| 缓存策略 | 响应速度提升70% |
原则9：版本控制原则
使用Git进行版本控制，为每个Skill创建独立分支。
原则10：测试驱动原则
- 为每个Skill编写单元测试
- 进行集成测试
- 生产部署前充分测试
二、SKILL.md主文件技巧
技巧3：用$ARGUMENTS实现参数传入
markdown
## 输入处理
如果 $ARGUMENTS 不为空，直接基于它开始分析。
如果 $ARGUMENTS 为空，主动询问用户：
1. 要测试的功能是什么？
2. 有需求文档或接口文档吗？
3. 有没有特别关注的测试维度？技巧4：给信息，别设限
推荐做法：写一个"生成API文档"的Skill时，给出API的规范是什么
错误做法：写死了输入输出格式、章节顺序、示例数量等太具体的要求
技巧5：拆解内容，三层加载架构
元数据层（始终加载）→ front matter决定技能是否激活
指令层（激活时加载）→ SKILL.md主体包含核心工作流程
资源层（按需加载）→ 参考文件，根据任务上下文有条件加载案例：品牌风格Skill
| 场景 | 加载 |
|---|---|
| 创建演示文稿 | 读 slide-decks.md |
| 创建专业文档 | 读 docs.md |
两个场景互不污染，各自用最小上下文。
技巧12：Description是触发器，写给机器看
推荐做法：
yaml
description: "当用户要求写周报、生成周报、输出工作汇报时触发"错误做法：
yaml
description: "这是一个帮助生成周报的Skill"关键：Description回答"什么时候用这个Skill"，不是"这个Skill是做什么的"
技巧14：负样本设计
明确说明不应该触发该Skill的情况：
yaml
description: |
Process Excel files and generates reports. Use when working with spreadsheets.
Do not use for CSV files or database exports.技巧15：多场景触发设计
Description包含多种用户可能使用的触发短语和表达方式。
技巧16：流程要有明确的"步骤感"
markdown
## 执行步骤
1. 分析输入
2. 提取关键信息
3. 生成输出
4. 验证结果技巧17：显性要求"xx数据必须具体"
有助于结果的真实性。
三、核心技巧清单（精简版）
| 编号 | 技巧 |
|---|---|
| 原则1 | 单一、分层、清晰、明确、灵活、复用、工程化 |
| 原则2 | 单一职责优先，避免"万能Skill" |
| 技巧3 | 用$ARGUMENTS实现灵活参数传入 |
| 技巧4 | 给信息，别设限 |
| 技巧5 | 三层加载架构：元数据→指令→资源 |
| 原则6 | 一致性：命名、格式、术语统一 |
| 原则7 | 安全性：防止命令注入、最小权限 |
| 原则8 | 性能优化：提示词压缩、智能路由、缓存 |
| 原则9 | 版本控制：Git追踪变更 |
| 原则10 | 测试驱动：单元测试+集成测试 |
| 技巧12 | Description是触发器，精准列清触发词 |
| 技巧14 | 负样本设计，明确不触发的情况 |
| 技巧15 | 多场景触发，覆盖用户各种表达方式 |
| 技巧16 | 流程要有步骤感 |
| 技巧17 | 显性要求数据具体 |
四、完整100例获取
因文章内容长度限制，完整100例技巧清单：
- 关注公众号+入群获取
- 持续交流分享
关键词：Skill, AI Agent, 技能设计, SKILL.md, 最佳实践, OpenClaw
