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/api-docs.md)
- 更多示例：参阅 [reference/examples.md](reference/examples.md)第七步：添加支持文件（可选）
为渐进式披露创建额外文件：
reference/ 目录：详细 API 文档、高级选项 scripts/ 目录：辅助脚本和工具 config.json：配置数据（如常用流水线列表）
从 SKILL.md 引用它们：
详细用法请参阅 [reference/api-docs.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/
\`\`\`
## 最佳实践
1. 遵循分层架构
2. 使用依赖注入
3. 编写单元测试工具集成类 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/examples.md)
详细参考：参阅 [reference/api-docs.md](reference/api-docs.md)
## 指引
1. 收集需求
2. 设计端点
3. 使用 OpenAPI 规范文档化
4. 根据最佳实践审查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，遵循所有最佳实践和验证规则。