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？
   • 它需要哪些工具或资源？
   • 此 Skill 用于个人用途还是团队共享？

2. 保持专注：一个 Skill = 一项能力

   • 合适：“PDF 表单填写”“Excel 数据分析”
   • 范围过广：“文档处理”“数据工具”

步骤 2：选择 Skill 位置

确定要在哪里创建 Skill：

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

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

项目 Skills（.agents/skills/；Claude Code 会将 .claude/skills 链接到此处）：

• 团队工作流和规范
• 项目专属专业知识
• 共享实用工具（提交到 git）

步骤 3：创建 Skill 结构

创建目录和文件：

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

# Project
mkdir -p .agents/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 .agents/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 前置元数据有效
• 指令采用分步形式
• 示例具体且符合实际
• 已记录依赖项
• 文件路径使用正斜杠
• Skill 会在相关查询中激活
• Claude 能正确遵循指令

故障排除

Skill 未激活：

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

多个 Skill 发生冲突：

• 让描述更具区分度
• 使用不同的触发词
• 缩小每个 Skill 的范围

Skill 出错：

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

示例

请参阅文档中的完整示例：

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

输出格式

创建 Skill 时，我将：

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

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