skill-writer

用途

Skill Writer 帮助用户为 Claude Code 创建结构良好、符合最佳实践与校验要求的 Agent Skills。当用户需要创建新技能、编写或更新 SKILL.md 文件、设计技能结构与 frontmatter、排查技能发现问题，或把现有提示词与工作流转换为技能时，可使用它。

主要能力

引导确定技能范围，强调“一个技能 = 一个能力”，避免范围过宽。
指导选择技能存放位置：个人级 ~/.claude/skills/ 与项目级 .claude/skills/。
指导创建技能目录与文件结构，支持多文件技能（SKILL.md、reference.md、examples.md、scripts/、templates/）。
指导编写 SKILL.md 的 YAML frontmatter，包括必填与可选字段。
指导撰写有效的 description，包含“做什么”“何时使用”和关键触发词。
提供内容结构建议：快速开始、指令、示例、最佳实践、要求等。
提供校验清单、测试方法与常见问题排查。
给出只读技能、脚本型技能、多文件渐进披露等常见模式。

使用方式

Skill Writer 本身以“指令”形式给出创建技能的操作步骤，主要流程为：

确定技能范围：通过提问明确能力、触发时机、所需工具资源、个人或团队用途；保持聚焦。
选择技能位置：个人技能或个人实验性技能放在 ~/.claude/skills/，团队工作流、项目专属能力或共享工具放在 .claude/skills/。

创建技能结构：

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

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

多文件结构示例：

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

编写 SKILL.md frontmatter：
```
---
name: skill-name
description: Brief description of what this does and when to use it
---
```
字段要求：
- name：仅小写字母、数字、连字符，最长 64 字符，必须与目录名一致。
- description：最长 1024 字符，必须同时包含“做什么”和“何时使用”，使用用户会说的具体触发词，提及文件类型、操作和上下文。
- 可选字段 allowed-tools：限制工具访问（逗号分隔），如 allowed-tools: Read, Grep, Glob，适用于只读技能、安全敏感工作流、有限范围操作。
撰写有效描述，公式为：[做什么] + [何时使用] + [关键触发词]。
组织技能内容：使用清晰的 Markdown 段落，如概览、快速开始、指令、示例、最佳实践、要求。
添加辅助文件（可选）：reference.md、examples.md、scripts/、templates/，并从 SKILL.md 中引用。
校验技能：检查文件结构、YAML frontmatter、内容质量和测试情况。
测试技能：重启 Claude Code 加载技能，用与描述匹配的问题验证是否自动激活、是否遵循指令。
必要时调试：若 Claude 未使用该技能，可让描述更具体、添加触发词、检查文件位置、校验 YAML、运行 claude --debug。

描述示例：

# ✅ Good
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.

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

# ❌ Too vague
description: Helps with documents
description: For data analysis

常见模式示例：

只读技能：

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

脚本型技能：

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

python scripts/process.py input.csv --output results.json
python scripts/validate.py results.json

多文件渐进披露技能：

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

在 SKILL.md 中可引用：Quick start: See [examples.md](examples.md)、Detailed reference: See [reference.md](reference.md)。

最佳实践

一个技能一个用途，不要创建超大技能。
描述要具体，包含用户会说的触发词。
指令写给 Claude 看，而非写给人看。
提供真实代码示例，而非伪代码。
列出依赖，在描述中说明所需包。
与队友一起测试激活情况和清晰度。
为技能记录版本变化。
使用渐进披露，把高级细节放在单独文件中。

校验清单

名称小写、仅连字符、最长 64 字符。
描述具体且不超过 1024 字符。
描述包含“做什么”和“何时使用”。
YAML frontmatter 有效。
指令为分步形式。
示例具体真实。
依赖已记录。
文件路径使用正斜杠。
技能能在相关查询上激活。
Claude 能正确遵循指令。

适用场景

为 Claude Code 创建新的 Agent Skill。
编写或更新 SKILL.md。
设计技能结构与 frontmatter。
排查技能发现问题。
将现有提示词或工作流转换为技能。

限制

资料未说明 Skill Writer 的具体收费、价格、平台支持范围、实际效果指标或安装方式，暂未提供。其内容以创建 Claude Code Agent Skill 的指导流程为主。