skill-writer

Skill 编写器

此 Skill 可帮助你为 Claude Code 创建结构良好的 Agent Skills，并遵循最佳实践和验证要求。

何时使用此 Skill

在以下情况下使用此 Skill：

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

说明

步骤 1：确定 Skill 范围

首先，了解 Skill 应该实现什么功能：

1. 提出澄清问题：

   • 此 Skill 应提供什么具体能力？
   • Claude 应在什么情况下使用此 Skill？
   • 它需要哪些工具或资源？
   • 这是供个人使用，还是供团队共享？

2. 聚焦范围：一个 Skill = 一项能力

   • 好的示例：“PDF 表单填写”“Excel 数据分析”
   • 范围过宽的示例：“文档处理”“数据工具”

步骤 2：选择 Skill 位置

确定要在哪里创建 Skill：

个人 Skills（~/.claude/skills/）：

• 个人工作流和偏好
• 实验性 Skills
• 个人效率工具

项目 Skills（.claude/skills/）：

• 团队工作流和约定
• 项目专属专业知识
• 共享工具（提交到 git）

步骤 3：创建 Skill 结构

创建目录和文件：

# Personal
mkdir -p ~/.claude/skills/skill-name

# Project
mkdir -p .claude/skills/skill-name

对于多文件 Skills：

skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── examples.md (optional)
├── scripts/
│   └── helper.py (optional)
└── templates/
    └── template.txt (optional)

步骤 4：编写 SKILL.md frontmatter

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

---
name: skill-name
description: Brief description of what this does and when to use it
---

字段要求：

• name：

  • 仅使用小写字母、数字和连字符
  • 最多 64 个字符
  • 必须与目录名称一致
  • 好的示例：pdf-processor、git-commit-helper
  • 不好的示例：PDF_Processor、Git Commits!

• description：

  • 最多 1024 个字符
  • 同时包含功能说明和使用时机
  • 使用用户可能会说的具体触发词
  • 提及文件类型、操作和使用场景

可选的 frontmatter 字段：

• allowed-tools：限制工具访问权限（以逗号分隔的列表）

  allowed-tools: Read, Grep, Glob
  

  适用于：
  • 只读 Skills
  • 对安全敏感的工作流
  • 范围受限的操作

步骤 5：编写有效的描述

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

公式：[功能] + [使用时机] + [关键触发词]

示例：

✅ 好的示例：

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

✅ 好的示例：

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

❌ 过于含糊：

description: Helps with documents
description: For data analysis

提示：

• 包含具体的文件扩展名（.pdf、.xlsx、.json）
• 提及常见的用户表达（“分析”“提取”“生成”）
• 列出具体操作（不要使用泛泛的动词）
• 添加场景线索（“在……时使用”“用于……”）

步骤 6：组织 Skill 内容

使用清晰的 Markdown 章节：

# Skill Name

Brief overview of what this Skill does.

## Quick start

Provide a simple example to get started immediately.

## Instructions

Step-by-step guidance for Claude:
1. First step with clear action
2. Second step with expected outcome
3. Handle edge cases

## Examples

Show concrete usage examples with code or commands.

## Best practices

- Key conventions to follow
- Common pitfalls to avoid
- When to use vs. not use

## Requirements

List any dependencies or prerequisites:
```bash
pip install package-name

高级用法

复杂场景请参阅 reference.md。

### Step 7: Add supporting files (optional)

Create additional files for progressive disclosure:

**reference.md**: Detailed API docs, advanced options
**examples.md**: Extended examples and use cases
**scripts/**: Helper scripts and utilities
**templates/**: File templates or boilerplate

Reference them from SKILL.md:
```markdown
For advanced usage, see [reference.md](reference.md).

Run the helper script:
\`\`\`bash
python scripts/helper.py input.txt
\`\`\`

步骤 8：验证 Skill

检查以下要求：

✅ 文件结构：

• SKILL.md 位于正确的位置
• 目录名称与 frontmatter 中的 name 一致

✅ YAML frontmatter：

• 第 1 行以 --- 开头
• 正文前有结尾的 ---
• YAML 有效（不含制表符，缩进正确）
• name 符合命名规则
• description 具体且少于 1024 个字符

✅ 内容质量：

• 为 Claude 提供清晰的说明
• 提供具体示例
• 处理边缘情况
• 列出依赖项（如有）

✅ 测试：

• 描述与用户问题相符
• Skill 会在相关查询中激活
• 说明清晰且可执行

步骤 9：测试 Skill

1. 重启 Claude Code（如果正在运行），以加载 Skill

2. 提出与描述相符的相关问题：

   Can you help me extract text from this PDF?
   

3. 验证激活情况：Claude 应自动使用 Skill

4. 检查行为：确认 Claude 正确遵循说明

步骤 10：按需调试

如果 Claude 没有使用 Skill：

1. 让描述更具体：

   • 添加触发词
   • 包含文件类型
   • 提及常见的用户表达

2. 检查文件位置：

   ls ~/.claude/skills/skill-name/SKILL.md
   ls .claude/skills/skill-name/SKILL.md
   

3. 验证 YAML：

   cat SKILL.md | head -n 10
   

4. 运行调试模式：

   claude --debug
   

常见模式

只读 Skill

---
name: code-reader
description: Read and analyze code without making changes. Use for code review, understanding codebases, or documentation.
allowed-tools: Read, Grep, Glob
---

基于脚本的 Skill

---
name: data-processor
description: Process CSV and JSON data files with Python scripts. Use when analyzing data files or transforming datasets.
---

# Data Processor

## Instructions

1. Use the processing script:
\`\`\`bash
python scripts/process.py input.csv --output results.json
\`\`\`

2. Validate output with:
\`\`\`bash
python scripts/validate.py results.json
\`\`\`

支持渐进式披露的多文件 Skill

---
name: api-designer
description: Design REST APIs following best practices. Use when creating API endpoints, designing routes, or planning API architecture.
---

# API Designer

Quick start: See [examples.md](examples.md)

Detailed reference: See [reference.md](reference.md)

## Instructions

1. Gather requirements
2. Design endpoints (see examples.md)
3. Document with OpenAPI spec
4. Review against best practices (see reference.md)

Skill 作者的最佳实践

1. 一个 Skill，一个用途：不要创建功能庞杂的 Skill
2. 描述具体：包含用户会说的触发词
3. 指令清晰：为 Claude 编写，而不是为人类编写
4. 示例具体：展示真实代码，而不是伪代码
5. 列出依赖项：在描述中提及所需的软件包
6. 与队友一起测试：验证激活效果和清晰度
7. 为 Skill 标注版本：在内容中记录更改
8. 使用渐进式披露：将高级详情放在单独的文件中

验证清单

定稿 Skill 之前，请确认：

• 名称使用小写字母和连字符，最多 64 个字符
• 描述具体且少于 1024 个字符
• 描述包含“是什么”和“何时使用”
• YAML frontmatter 格式有效
• 指令按步骤编写
• 示例具体且符合实际
• 已记录依赖项
• 文件路径使用正斜杠
• Skill 会在相关查询中激活
• Claude 能正确遵循指令

故障排除

Skill 未激活：

• 在描述中添加更具体的触发词
• 在描述中包含文件类型和操作
• 添加包含用户常用措辞的“在……时使用”条款

多个 Skill 发生冲突：

• 让描述更加各具特色
• 使用不同的触发词
• 缩小每个 Skill 的范围

Skill 出现错误：

• 检查 YAML 语法（不能使用制表符，缩进必须正确）
• 验证文件路径（使用正斜杠）
• 确保脚本具有执行权限
• 列出所有依赖项

示例

完整示例请参阅文档：

• 简单的单文件 Skill（commit-helper）
• 带工具权限的 Skill（code-reviewer）
• 多文件 Skill（pdf-processing）

输出格式

创建 Skill 时，我将：

1. 询问有关范围和要求的澄清问题
2. 建议 Skill 名称和位置
3. 创建格式正确且包含 frontmatter 的 SKILL.md 文件
4. 添加清晰的指令和示例
5. 根据需要添加辅助文件
6. 提供测试说明
7. 根据所有要求进行验证

最终结果将是一个完整、可用的 Skill，并遵循所有最佳实践和验证规则。