如何写好一个skill

什么是Skill?

Skill是一种结构化的Prompt Engineering --- 通过标准化的文件格式，把分散在人脑中的领域知识，操作流程和最佳实践，转换为AI可理解，可执行的指令集。

内容：

指令（告诉AI该怎么干活，按什么步骤来）；
上下文（给AI补课，告诉它你的项目背景、团队规范这些它不可能凭空知道的东西）
工具（Tools）：一些辅助脚本、配置模板，AI 可以直接拿来用

Skill 是怎么运作的？

Anthropic 中设计三层：

第一层：元数据（name + description)100字以内

举个例子，假如说要实现一个相机功能渲染，name 是 camera-widget-render , description 是处理

CameraWidget 的 VTK 渲染逻辑和坐标映射。当用户需要修改相机视角、追踪点渲染或坐标转换时应该触发，也就是说清楚到底name

是干嘛的，什么时候用这个name。

SKILL.md 主体（skill被匹配触发的时候加载）
附带的脚本和参考资料（执行过程中按需引用）
再次举一个例子，还是那个相机功能渲染的例子，附带的脚本和参考资料指的就是 skill.md中对于当前元数据的 description 是怎么实现的在skill.md中的某个地方有规定的实现，参考哪个，说明方法让ai 自己做。

bash 复制代码

Level 1 (常驻):
  name: camera-widget-render
  description: 处理 CameraWidget 的 VTK 渲染...

      ↓ 用户问 "我想改追踪点的颜色"

Level 2 (触发加载):
  加载整份 SKILL.md 正文，AI 看到：
  "追踪点样式修改 → 去读 references/tracking-dot-setup.md"

      ↓ AI 按照 SKILL.md 的指引

Level 3 (按需读):
  AI 读取 references/tracking-dot-setup.md
  拿到具体代码调用方式后，开始修改 CameraWidget.cpp

skill 长什么样？

比较复杂的一些skill.md 包括

bash 复制代码

my-skill/
├── SKILL.md              # 核心指令文件（必需）
├── scripts/              # 可执行脚本（可选）
│   ├── check.sh
│   └── transform.py
├── references/           # 参考文档（可选）
│   ├── api-spec.md
│   └── style-guide.md
└── assets/               # 静态资源（可选）
    └── template.json

怎么写一个skill.md?

Skill.md 分两部分：上面是一段 YAML 头信息（告诉系统这个 Skill 叫什么、干什么），下面是 Markdown 正文（具体的指令和说明）。

YAML 头信息部分（放在文件最上面）：

bash 复制代码

name: my-skill-name           # 必需：唯一标识符，小写，用连字符分隔
description: >                 # 必需：清晰描述功能和触发场景
  将项目中的旧版 HTTP 客户端迁移到新版统一请求库。
  适用于 Go 项目中使用了 old-http-client 模块，
  需要替换为 unified-httpclient 的场景。
license: MIT                   # 可选：许可证
metadata:                      # 可选：扩展元数据
  author: TeamName
    version: "1.0"

💡 关于 description 的语言：建议用中文编写（如果团队和 AI 工具主要使用中文对话），也可以中英双语，以提高触发匹配率。

Markdown 正文部分（参考模板，不用死板照搬，参考结构即可）：

Skill 名称

bash 复制代码

## 概述
描述 Skill 的目的、适用场景和核心价值。

## 前置条件
执行前需要满足的条件和检查步骤。

## 处理步骤
### Step 1: xxx
### Step 2: xxx

## 代码示例
Before/After 对比或 Few-Shot 示例。

## 验证清单
- [ ] 检查项 1
- [ ] 检查项 2

## 常见问题
### Q: xxx？
A: xxx

怎么写好一个skill

Description 写好了，一切就成功了一半（举个例子）

bash 复制代码

 SKILL.md（name + description + 步骤 + 脚本引用）
         ↓
2. 你在聊天框里发消息："帮我把追踪点颜色改成红色"
         ↓
3. AI 根据 name + description 匹配 → 发现跟 "camera-widget-render" 匹配
         ↓
4. AI 加载 SKILL.md 完整正文
         ↓
5. AI 按 SKILL.md 步骤执行，必要时去读 scripts/ 或 references/ 里的文件
         ↓
6. AI 写出符合规范的代码

开头就说清楚：做什么、为什么、要不要做

别让 AI 猜你的意图。每个 Skill 上来就该把三件事说明白：做什么、为什么、怎么判断是否需要做。

把起点和终点说清楚------从哪迁到哪，别含糊告诉 AI 什么时候不用做------给个前置检查条件，及时跳过

给出具体的检查命令，而非模糊描述

用祈使句下指令，解释"为什么"（不用商量的语句，直接说做什么；讲清楚为什么，不要用Must）
给出"改之前 vs 改之后"的对比
善用可视化：决策树与流程图

总结：写好 Skill 的核心检查清单

写的内容对不对

目标明确：做什么、为什么做、什么时候触发
Description 精准：AI 能不能在合适的时候自动匹配到
语气直接吗：是不是在直接下指令，而不是绕弯子
讲了为什么吗：不只是说"必须这样做"，还解释了原因
例子够不够：有没有 3-5 个 Before/After 对比或者示例
场景考虑全了吗：多种情况都覆盖到了，有决策树或分支处理
坑标出来了吗：容易犯的错误和注意事项是否标注了
能验证吗：有验证清单和能跑的检查命令

结构合不合理

YAML 元数据完整：name 和 description 都填了，description 足够详细
篇幅合理：SKILL.md 正文控制在 500 行以内
模块化拆分：超过 500 行的要拆成主 Skill + 子 Skill
依赖明确：清楚声明前置条件和相关 Skill
可视化表达：善用表格、ASCII 流程图组织信息

工程结构合不合理

版本控制：版本号合理，改了什么有迹可循
可独立使用：拆出来的子 Skill 脱离主流程也能跑
持续迭代：定期根据反馈优化
评估验证：通过测试用例验证了效果
团队协作：通过 PR Review 合入，维护变更日志

安全过关了吗

无硬编码密钥：文件中没有 API Key、密码、Token 等敏感信息
危险操作有确认：删除、覆盖、DDL 等操作有确认机制或备份步骤
输入有校验：脚本中的用户输入做了验证，不会被注入
路径安全：文件路径操作没有使用未经验证的变量拼接
网络请求安全：使用 HTTPS，并设置了合理的超时

可维护性够好吗

避免了常见反模式：对照"常见反模式"逐条检查
脚本跨平台兼容：在 macOS / Linux 上都能正常运行
关键步骤有检查点：不是一口气跑完才验证，中间有自检