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，遵循所有最佳实践和验证规则。