48-skill-writer

# Skill Writer

本 Skill 帮助你为 CodeBuddy 创建结构良好、符合最佳实践和验证要求的 Agent Skills。

## 触发条件

当用户需要：
- 创建新的 Agent Skill
- 编写或更新 SKILL.md 文件
- 设计 skill 结构和 frontmatter
- 排查 skill 发现问题
- 将现有提示词或工作流转换为 Skills

## 指引

### 第一步：确定 Skill 范围

首先，理解 Skill 应该做什么：

1. **询问澄清问题**：
   - 这个 Skill 应该提供什么具体能力？
   - 什么时候应该使用这个 Skill？
   - 它需要什么工具或资源？
   - 是个人使用还是团队共享？

2. **保持聚焦**：一个 Skill = 一个能力
   - 好的：「PDF 表单填写」、「Excel 数据分析」、「流水线模板管理」
   - 太宽泛：「文档处理」、「数据工具」

### 第二步：选择 Skill 位置

确定在哪里创建 Skill：

**项目级 Skills**（`.codebuddy/skills/`）：
- 团队工作流和约定
- 项目特定的专业知识
- 共享工具（提交到 git）
- **推荐用于团队协作项目**

**用户级 Skills**（`~/.codebuddy/skills/`）：
- 个人工作流和偏好
- 实验性 Skills
- 个人生产力工具

### 第三步：创建 Skill 结构

创建目录和文件：

```bash
# 项目级（推荐）
mkdir -p .codebuddy/skills/skill-name

# 用户级
mkdir -p ~/.codebuddy/skills/skill-name
```

**基本结构**：
```
skill-name/
├── SKILL.md          # 必需 - 主文件
├── reference/        # 可选 - 参考文档目录
│   ├── api-docs.md
│   └── examples.md
├── scripts/          # 可选 - 辅助脚本
│   └── helper.py
└── config.json       # 可选 - 配置文件
```

### 第四步：编写 SKILL.md frontmatter

创建包含必需字段的 YAML frontmatter：

```yaml
---
name: skill-name
description: 简要描述这个 Skill 做什么以及何时使用它
---
```

**字段要求**：

- **name**：
  - 仅允许小写字母、数字、连字符
  - 最多 64 个字符
  - 必须与目录名匹配
  - 好的：`pdf-processor`、`git-commit-helper`、`pipeline-manager`
  - 不好的：`PDF_Processor`、`Git Commits!`

- **description**：
  - 最多 1024 个字符
  - 同时包含「做什么」和「何时使用」
  - 使用用户可能会说的具体触发词
  - 提及文件类型、操作和上下文

### 第五步：编写有效的描述

描述对于 CodeBuddy 发现你的 Skill 至关重要。

**公式**：`[做什么] + [何时使用] + [关键触发词]`

**示例**：

✅ **好的**：
```yaml
description: 管理蓝盾流水线的构建操作，包括查询构建历史、获取启动参数、查看构建状态、启动构建。当用户提及流水线、构建、部署、CI/CD、蓝盾或需要触发构建任务时使用。
```

✅ **好的**：
```yaml
description: 后端微服务开发规范，包括目录结构、分层架构、依赖注入、配置管理。当用户进行后端开发、创建新服务、编写 API 时使用。
```

❌ **太模糊**：
```yaml
description: 帮助处理文档
description: 用于数据分析
```

**技巧**：
- 包含具体文件扩展名（.pdf、.xlsx、.json）
- 提及常见用户短语（「分析」、「提取」、「生成」、「创建」）
- 列出具体操作（而非泛泛的动词）
- 添加上下文线索（「当用户...时使用」）

### 第六步：组织 Skill 内容

使用清晰的 Markdown 结构：

```markdown
# Skill 名称

简要概述这个 Skill 做什么。

## 触发条件

明确说明何时应该使用这个 Sk