Skill Writer
本 Skill 帮助你创建结构良好、符合最佳实践和验证要求的 Agent Skills，适用于 CodeBuddy、Cursor 等支持 Skill 系统的 IDE。
触发条件
当用户需要：
-
创建新的 Agent Skill
-
编写或更新 SKILL.md 文件
-
设计 skill 结构和 frontmatter
-
排查 skill 发现问题
-
将现有提示词或工作流转换为 Skills
指引
第一步：确定 Skill 范围
首先，理解 Skill 应该做什么：
询问澄清问题：
-
这个 Skill 应该提供什么具体能力？
-
什么时候应该使用这个 Skill？
-
它需要什么工具或资源？
-
是个人使用还是团队共享？
保持聚焦：一个 Skill = 一个能力
-
好的：「PDF 表单填写」、「Excel 数据分析」、「流水线模板管理」
-
太宽泛：「文档处理」、「数据工具」
第二步：选择 Skill 位置
确定在哪里创建 Skill：
项目级 Skills（.codebuddy/skills/ 或 .cursor/skills/ ）：
-
团队工作流和约定
-
项目特定的专业知识
-
共享工具（提交到 git）
-
推荐用于团队协作项目
用户级 Skills（~/.codebuddy/skills/ 或 ~/.cursor/skills/ ）：
-
个人工作流和偏好
-
实验性 Skills
-
个人生产力工具
注意: 不同 IDE 使用不同的目录名：
-
CodeBuddy: .codebuddy/ 或 ~/.codebuddy/
-
Cursor: .cursor/ 或 ~/.cursor/
-
其他 IDE 可能使用不同的目录结构
第三步：创建 Skill 结构
创建目录和文件：
项目级（推荐）- CodeBuddy
mkdir -p .codebuddy/skills/skill-name
项目级（推荐）- Cursor
mkdir -p .cursor/skills/skill-name
用户级 - CodeBuddy
mkdir -p ~/.codebuddy/skills/skill-name
用户级 - Cursor
mkdir -p ~/.cursor/skills/skill-name
基本结构：
skill-name/ ├── SKILL.md # 必需 - 主文件 ├── reference/ # 可选 - 参考文档目录 │ ├── api-docs.md │ └── examples.md ├── scripts/ # 可选 - 辅助脚本 │ └── helper.py └── config.json # 可选 - 配置文件
第四步：编写 SKILL.md frontmatter
创建包含必需字段的 YAML frontmatter：
name: skill-name description: 简要描述这个 Skill 做什么以及何时使用它
字段要求：
name：
-
仅允许小写字母、数字、连字符
-
最多 64 个字符
-
必须与目录名匹配
-
好的：pdf-processor 、git-commit-helper 、pipeline-manager
-
不好的：PDF_Processor 、Git Commits!
description：
-
最多 1024 个字符
-
同时包含「做什么」和「何时使用」
-
使用用户可能会说的具体触发词
-
提及文件类型、操作和上下文
第五步：编写有效的描述
描述对于 AI 助手发现你的 Skill 至关重要。
公式：[做什么] + [何时使用] + [关键触发词]
示例：
✅ 好的：
description: 管理蓝盾流水线的构建操作，包括查询构建历史、获取启动参数、查看构建状态、启动构建。当用户提及流水线、构建、部署、CI/CD、蓝盾或需要触发构建任务时使用。
✅ 好的：
description: 后端微服务开发规范，包括目录结构、分层架构、依赖注入、配置管理。当用户进行后端开发、创建新服务、编写 API 时使用。
❌ 太模糊：
description: 帮助处理文档 description: 用于数据分析
技巧：
-
包含具体文件扩展名（.pdf、.xlsx、.json）
-
提及常见用户短语（「分析」、「提取」、「生成」、「创建」）
-
列出具体操作（而非泛泛的动词）
-
添加上下文线索（「当用户...时使用」）
第六步：组织 Skill 内容
使用清晰的 Markdown 结构：
Skill 名称
简要概述这个 Skill 做什么。
触发条件
明确说明何时应该使用这个 Skill。
核心概念
解释关键术语和概念。
常用工作流
工作流 1：xxx
步骤 1：xxx 步骤 2：xxx 步骤 3：xxx
快速示例
展示具体的使用示例。
最佳实践
- 要遵循的关键约定
- 要避免的常见陷阱
工具参考
如有额外文档，链接到 reference/ 目录：
- 详细 API 文档：参阅 reference/api-docs.md
- 更多示例：参阅 reference/examples.md
第七步：添加支持文件（可选）
为渐进式披露创建额外文件：
reference/ 目录：详细 API 文档、高级选项 scripts/ 目录：辅助脚本和工具 config.json：配置数据（如常用流水线列表）
从 SKILL.md 引用它们：
详细用法请参阅 reference/api-docs.md。
运行辅助脚本： ```bash python scripts/helper.py input.txt ```
第八步：验证 Skill
检查以下要求：
✅ 文件结构：
-
SKILL.md 存在于正确位置
-
目录名与 frontmatter 中的 name 匹配
✅ YAML frontmatter：
-
第一行是 ---
-
内容前有闭合的 ---
-
有效的 YAML（无制表符，正确缩进）
-
name 遵循命名规则
-
description 具体且少于 1024 字符
✅ 内容质量：
-
为 AI 助手提供清晰的指令
-
提供具体示例
-
处理边缘情况
-
列出依赖项（如有）
✅ 测试：
-
描述与用户问题匹配
-
Skill 在相关查询时激活
-
指令清晰可操作
第九步：测试 Skill
重启 IDE（如正在运行）以加载 Skill
提出相关问题，匹配描述：
帮我管理流水线构建
验证激活：AI 助手应自动使用该 Skill
检查行为：确认 AI 助手正确遵循指令
第十步：调试（如需要）
如果 AI 助手没有使用 Skill：
使描述更具体：
-
添加触发词
-
包含文件类型
-
提及常见用户短语
检查文件位置：
CodeBuddy
ls .codebuddy/skills/skill-name/SKILL.md ls ~/.codebuddy/skills/skill-name/SKILL.md
Cursor
ls .cursor/skills/skill-name/SKILL.md ls ~/.cursor/skills/skill-name/SKILL.md
验证 YAML：
cat SKILL.md | head -n 10
常见模式
开发规范类 Skill
name: backend-development description: 后端微服务开发规范，包括目录结构、分层架构、依赖注入。当用户进行后端开发、创建新服务时使用。
后端微服务开发
触发条件
当用户需要创建新服务、编写后端代码、设计 API 时使用。
目录结构
``` service-name/ ├── api/ ├── biz/ └── boot/ ```
最佳实践
- 遵循分层架构
- 使用依赖注入
- 编写单元测试
工具集成类 Skill
name: pipeline-manager description: 管理蓝盾流水线的构建操作。当用户提及流水线、构建、部署、CI/CD 时使用。
流水线管理
通过 MCP 工具管理流水线。
核心概念
- projectId：项目英文名
- pipelineId：流水线 ID
常用工作流
启动构建
``` 步骤 1：获取启动参数 步骤 2：向用户确认 步骤 3：启动构建 ```
多文件渐进式披露 Skill
name: api-designer description: 设计 REST API，遵循最佳实践。当用户创建 API 端点、设计路由或规划 API 架构时使用。
API 设计器
快速入门：参阅 reference/examples.md
详细参考：参阅 reference/api-docs.md
指引
- 收集需求
- 设计端点
- 使用 OpenAPI 规范文档化
- 根据最佳实践审查
Skill 作者最佳实践
-
一个 Skill，一个目的：不要创建超大 Skill
-
具体的描述：包含用户会说的触发词
-
清晰的指令：为 AI 助手编写，而非人类
-
具体的示例：展示真实代码，而非伪代码
-
列出依赖：在描述中提及所需包
-
与团队测试：验证激活和清晰度
-
版本控制：在内容中记录变更
-
渐进式披露：将高级细节放在单独文件中
验证清单
完成 Skill 前，验证：
-
名称是小写、仅连字符、最多 64 字符
-
描述具体且少于 1024 字符
-
描述包含「什么」和「何时」
-
YAML frontmatter 有效
-
指令是分步的
-
示例具体且现实
-
依赖项已记录
-
文件路径使用正斜杠
-
Skill 在相关查询时激活
-
AI 助手正确遵循指令
故障排除
Skill 不激活：
-
使描述更具体，添加触发词
-
在描述中包含文件类型和操作
-
添加「当用户...时使用」子句
多个 Skill 冲突：
-
使描述更加不同
-
使用不同的触发词
-
缩小每个 Skill 的范围
Skill 有错误：
-
检查 YAML 语法（无制表符，正确缩进）
-
验证文件路径（使用正斜杠）
-
确保脚本有执行权限
-
列出所有依赖项
示例参考
查看项目中现有的 Skills 作为参考：
-
简单单文件 Skill：git-commit-specification
-
带工具集成的 Skill：managing-devops-pipeline
-
多文件 Skill：process-module-architecture 系列
输出格式
创建 Skill 时，我将：
-
询问关于范围和需求的澄清问题
-
建议 Skill 名称和位置
-
创建带有正确 frontmatter 的 SKILL.md 文件
-
包含清晰的指令和示例
-
根据需要添加支持文件
-
提供测试说明
-
根据所有要求进行验证
结果将是一个完整、可用的 Skill，遵循所有最佳实践和验证规则。