【实战指南】如何写好一个Skill：SKILL.md规范、目录设计与5个编写技巧

目录摘要一、Skill是什么1.1 一句话定义1.2 Skill vs Prompt vs MCP1.3 支持Skill的平台二、目录结构详解2.1 标准目录2.2 每个目录的作用SKILL.md — 核心操作手册scripts/ — 确定性执行的脚本references/ — 详细参考文档assets/ — 配置模板和资源2.3 渐进式加载原理三、5个实战编写技巧3.1 技巧1description是灵魂3.2 技巧2先调研再写3.3 技巧3每个Skill只干一件事3.4 技巧4用代码代替文字四、完整Skill示例4.1 代码审查Skill输出格式⚠️ Gotchas摘要Agent Skills正在成为AI编程的核心扩展机制。本文从Skill的概念出发详解SKILL.md文件规范、目录结构中每个文件夹的作用、渐进式加载原理并分享5个实战编写技巧——从description编写到Gotchas防坑附完整代码示例帮助开发者写出高质量、可复用的Skill。关键词Agent Skills、SKILL.md、编写技巧、目录结构、渐进式加载、Cursor、Claude Code、CodeBuddy一、Skill是什么1.1 一句话定义Skill是写给AI Agent看的操作手册。它不是给人看的README。你把遇到某类问题该怎么处理写成一个标准化的SKILL.md文件AI就能按照你的规矩来执行特定任务。1.2 Skill vs Prompt vs MCP维度PromptSkillMCP本质单次对话指令持久化能力单元标准化工具接入协议生命周期用完就丢写一次永久复用编写一次全平台通用触发方式手动输入AI自动识别调用AI调用函数可带资源❌ 纯文字✅ 脚本文档资源✅ 工具定义团队共享❌ 难✅ Git管理✅ 注册表形象类比说一句话给一本操作手册装一个USB接口核心区别Skill解决怎么干知识流程MCP解决能不能连工具接口Prompt解决当下这一句即时指令。1.3 支持Skill的平台Cursor ✅ Claude Code ✅ CodeBuddy ✅ GitHub Copilot ✅ Windsurf ✅二、目录结构详解2.1 标准目录my-skill/ ├── SKILL.md ← 核心操作手册必须有 ├── scripts/ ← 可选自动化脚本 │ ├── deploy.sh │ └── validate.py ├── references/ ← 可选参考文档 │ ├── api-guide.md │ └── tone-guide.md └── assets/ ← 可选资源文件 └── config-template.json2.2 每个目录的作用SKILL.md — 核心操作手册唯一必须有的文件。包含两部分# Part 1: YAML Frontmatter元数据---name:code-reviewdescription:按团队标准审查代码。当用户要求review、审查、检查代码质量时使用。allowed-tools:Read,Bash(grep:*)---# Part 2: Markdown Body正文指令## 审查步骤1. 架构维度 2. 异常处理 3. 日志规范 4. 安全风险YAML Frontmatter字段说明字段必需说明约束name✅Skill唯一标识小写连字符1-64字符description✅告诉AI何时使用 1024字符allowed-tools可选允许使用的工具白名单如 Read, Write, Bashcontext可选fork隔离子代理fork/默认agent可选指定子代理类型仅context:fork时有效license可选许可证MIT, Apache-2.0等scripts/ — 确定性执行的脚本# scripts/check-deps.sh#!/bin/bash# 检查项目依赖是否存在安全漏洞echo正在检查依赖安全...npmaudit--production21exit_code$?if[$exit_code-ne0];thenecho⚠️ 发现安全漏洞请查看上方详情elseecho✅ 未发现安全漏洞fi为什么要用scripts而不是让AI直接写AI直接执行每次可能写出不同的检查逻辑不确定性 Scripts执行每次都跑同一个脚本确定性 需要精确执行的操作 → 写脚本 需要灵活判断的操作 → 写指令references/ — 详细参考文档# references/coding-standards.md ## 命名规范 - 变量camelCase - 常量UPPER_SNAKE_CASE - 函数camelCase动词开头 ## 错误处理 - 统一使用自定义AppError - 必须包含错误码和消息 - 禁止吞掉异常太长不适合放在SKILL.md正文里的内容放这儿。AI按需读取——需要的时候再去看不会一股脑全塞进上下文。assets/ — 配置模板和资源// assets/config-template.json{project:{{PROJECT_NAME}},version:1.0.0,database:{host:localhost,port:5432,name:{{DB_NAME}}}}AI在生成代码时可以直接引用这些模板保证输出符合团队规范。2.3 渐进式加载原理┌─────────────────────────────────────────┐ │ L1: Metadata (name description) │ ← 常驻上下文 (~100 tokens) │ AI看这个决定是否调用 │ ├─────────────────────────────────────────┤ │ L2: SKILL.md Body │ ← 触发时加载 (500行, 5K tokens) │ AI读这个了解怎么干 │ ├─────────────────────────────────────────┤ │ L3: references/ scripts/ assets/ │ ← 按需读取 (5K tokens/文件) │ AI需要细节时才去看 │ └─────────────────────────────────────────┘为什么这样设计上下文窗口是公共资源需要跟系统Prompt、对话历史、代码文件共享。如果10个Skill的全部内容都常驻上下文Token直接炸了。三、5个实战编写技巧3.1 技巧1description是灵魂AI靠description决定什么时候调用你的Skill。写差了等于白写。推荐模板Use when [触发条件/关键词] to [目标行动] by [核心操作] while [重要限制]对比示例等级description问题❌ 差“处理PDF”太笼统AI不知道什么时候用⚠️ 一般“PDF文件处理工具”缺少触发条件和能力边界✅ 好“从PDF文件中提取文本和表格填写PDF表单合并多个PDF。在用户提到PDF文档处理时使用。”触发条件能力范围清晰进阶加负面案例description:生成PPT演示文稿。Use when users mention PowerPoint, slides, or presentation. Do NOT use when user only needs a quick text summary.告诉AI什么时候不该用同样重要。3.2 技巧2先调研再写❌ 错误流程凭经验直接写 → 质量一般 ✅ 正确流程让AI调研最佳实践 → 基于调研结果写 → 质量翻倍操作方法你我想创建一个Go代码审查的Skill。 请先搜索Go代码审查的最佳实践、常见问题和社区推荐的检查维度 然后帮我设计一个完整的Skill结构。AI会自动完成调研→总结→结构设计。出来的Skill比你凭空想的专业10倍。3.3 技巧3每个Skill只干一件事❌ 全能型Skill1000行 code-review security-audit performance-check test-writing → AI蒙圈选择性忽略甚至幻觉 ✅ 单一职责Skill各100-300行 code-review/SKILL.md security-audit/SKILL.md performance-check/SKILL.md test-writer/SKILL.md → 各司其职精准触发判断标准SKILL.md超过500行→该拆了。3.4 技巧4用代码代替文字# ❌ 用文字描述 检查代码中是否有硬编码的密钥。具体来说需要搜索源代码文件 中包含password、secret、api_key等关键词的行判断它们是否 直接赋值为字符串常量... # ✅ 用代码命令 ## 检查硬编码密钥 运行以下命令 bash grep -rn password\|secret\|api_key\|token src/ \ --include*.go --include*.py --include*.js \ | grep -v test | grep -v mock如果有匹配结果标记为 [✗] 安全风险。AI读代码的准确度比读自然语言高得多。 ### 3.5 技巧5加Gotchas部分 **这是ROI最高的改进。** 专门写一段AI容易犯的错误和陷阱。 markdown ## ⚠️ Gotchas - **不要用 rm -rf 删除任何目录** — 使用 trash 命令代替 - **数据库操作前必须先备份** — 执行 scripts/backup.sh - **不要修改代码只做审查** — 这是review不是fix - **大文件(1000行)分段审查** — 一次性全读会超出上下文 - **遇到二进制文件直接跳过** — 不要尝试解析 .png/.pdf一个Gotcha能救你一条命。AI特别容易在边缘情况上翻车提前告诉它哪些坑不能踩。四、完整Skill示例4.1 代码审查Skill.codebuddy/skills/code-review/ ├── SKILL.md ├── scripts/ │ └── check-deps.sh └── references/ └── coding-standards.md# SKILL.md---name:code-reviewdescription:按团队标准审查代码质量。Use when users ask to review, audit, or check code quality. Covers architecture, error handling, logging, and security dimensions.allowed-tools:Read,Bash(grep:*),Bash(find:*)---# 代码审查 Skill## 审查流程### Step 1: 架构检查-模块拆分是否合理职责是否单一-执行 scripts/check-deps.sh 检查依赖安全### Step 2: 异常处理-外部调用是否有try-catch-是否使用自定义AppError见 references/coding-standards.md### Step 3: 日志规范-关键操作是否有structlog日志-是否包含trace_id### Step 4: 安全检查bash grep-rn password\|secret\|api_key src/--include*.go|grep-v test输出格式 代码审查报告 [✓/✗] [类别] 问题描述及修复建议 总结 通过: X/4 风险等级: 高/中/低⚠️ Gotchas不要修改代码只做审查大文件(1000行)分段审查遇到生成代码(.gen.go)跳过--- ## 五、质量检查清单 写完Skill后对照这份清单自查 - [ ] description是否明确了触发条件和能力边界 - [ ] SKILL.md是否少于500行 - [ ] 是否每个Skill只解决一个问题 - [ ] 是否有代码示例或命令模板而非纯文字 - [ ] 是否有Gotchas部分预防常见错误 - [ ] 详细文档是否移到了references/ - [ ] 需要确定性执行的操作是否写成了scripts - [ ] 是否在至少3个真实场景测试过正常/边缘/不适用 - [ ] 是否假设了工具已安装应明确写安装命令 - [ ] name是否全小写连字符 --- ## 六、总结 **Skill的本质是把人的经验变成AI的能力。** 写好一个Skill的核心 | 原则 | 一句话 | |------|--------| | description是灵魂 | 写差了等于白写 | | 先调研再写 | 质量差10倍 | | 单一职责 | 超过500行就该拆 | | 代码优于文字 | AI读代码更准确 | | Gotchas预防翻车 | ROI最高的一段 | 花半天写5个Skill之后每天省2小时。这笔账算得过来。 --- ## 参考资料 1. [Agent Skills | Cursor Docs](https://cursor.com/docs/skills) 2. [编写SKILL.md | Open Agent Skills](https://openagentskills.dev/zh/docs/writing-skill-md) 3. [如何写好AI Agent Skill | zayfEnClosure](https://www.zayfen.com/posts/how-to-write-agent-skills/) 4. [最佳实践 | Agent Skills学习及案例](https://www.claudeskills.org/zh/docs/agent-skills/best-practices) 5. [Best Practices for Creating Agent Skills | GitHub](https://github.com/mgechev/skills-best-practices) 6. [CodeBuddy Skills系统文档](https://www.codebuddy.cn/docs/cli/skills) --- ## 互动交流 你写过哪些好用的Skill踩过什么坑有什么独家心得 欢迎在评论区分享你的实战经验 - **收藏**本文 - **点赞**支持 - **转发**给同事 - **关注**我的CSDN