技能编写器

本技能可帮助你为 Claude Code 创建结构清晰、符合最佳实践和验证要求的智能体技能。

何时使用本技能

在以下场景使用本技能：

创建新的智能体技能
编写或更新 SKILL.md 文件
设计技能结构和前置元数据
排查技能发现问题
将现有提示词或工作流转换为技能

使用指南

步骤1：确定技能范围

首先，明确技能的核心功能：

提出澄清问题：
- 该技能应提供哪些具体功能？
- Claude 应在何时使用该技能？
- 它需要哪些工具或资源？
- 是个人使用还是团队共享？
聚焦单一功能：一个技能对应一个核心能力
- 推荐："PDF表单填写"、"Excel数据分析"
- 不推荐："文档处理"、"数据工具"（范围过宽）

步骤2：选择技能存储位置

确定技能的创建位置：

个人技能（~/.claude/skills/）：

个人工作流和偏好设置
实验性技能
个人 productivity 工具

项目技能（.claude/skills/）：

团队工作流和约定
项目特定专业技能
共享工具（可提交至Git）

步骤3：创建技能结构

创建目录和文件：

# 个人技能
mkdir -p ~/.claude/skills/skill-name

# 项目技能
mkdir -p .claude/skills/skill-name

多文件技能结构示例：

skill-name/
├── SKILL.md（必填）
├── reference.md（可选）
├── examples.md（可选）
├── scripts/
│   └── helper.py（可选）
└── templates/
    └── template.txt（可选）

步骤4：编写 SKILL.md 前置元数据

创建包含必填字段的 YAML 前置元数据：

---
name: skill-name
description: 简要描述该技能的功能及使用场景
---

字段要求：

name：
- 仅允许小写字母、数字和连字符
- 最多64个字符
- 必须与目录名一致
- 推荐：pdf-processor、git-commit-helper
- 不推荐：PDF_Processor、Git Commits!
description：
- 最多1024个字符
- 需同时包含功能描述和使用场景
- 使用用户可能会说的具体触发词
- 提及文件类型、操作和上下文

可选前置元数据字段：

allowed-tools：限制工具访问（逗号分隔列表）
```
allowed-tools: Read, Grep, Glob
```
适用场景：
- 只读技能
- 安全敏感工作流
- 有限范围操作

步骤5：编写有效描述

描述是 Claude 发现技能的关键。

公式：[功能] + [使用场景] + [关键触发词]

示例：

✅ 推荐：

description: 从PDF文件中提取文本和表格，填写表单，合并文档。当处理PDF文件或用户提到PDF、表单或文档提取时使用。

✅ 推荐：

description: 分析Excel表格，创建数据透视表和生成图表。当处理Excel文件、电子表格或分析.xlsx格式的表格数据时使用。

❌ 不推荐（过于模糊）：

description: 帮助处理文档
description: 用于数据分析

技巧：

包含具体文件扩展名（.pdf、.xlsx、.json）
提及常见用户短语（"分析"、"提取"、"生成"）
列出具体操作（避免泛泛而谈）
添加上下文线索（"当...时使用"、"用于..."）

步骤6：构建技能内容结构

使用清晰的 Markdown 章节：

# 技能名称

简要概述该技能的功能。

## 快速开始

提供简单示例帮助用户立即上手。

## 使用说明

为 Claude 提供分步指导：
1. 明确的第一步操作
2. 第二步的预期结果
3. 边界情况处理

## 示例

提供具体的使用示例（含代码或命令）。

## 最佳实践

- 需遵循的关键约定
- 常见陷阱及避免方法
- 使用与不使用的场景

## 依赖项

列出所有依赖或前置条件：
```bash
pip install package-name

高级用法

复杂场景请参考 reference.md。


### 步骤7：添加支持文件（可选）

创建额外文件实现渐进式披露：

**reference.md**：详细API文档、高级选项
**examples.md**：扩展示例和使用案例
**scripts/**：辅助脚本和工具
**templates/**：文件模板或 boilerplate

在 SKILL.md 中引用这些文件：
```markdown
高级用法请参考 [reference.md](reference.md)。

运行辅助脚本：
```bash
python scripts/helper.py input.txt


### 步骤8：验证技能

检查以下要求：

✅ **文件结构**：
- [ ] SKILL.md 位于正确路径
- [ ] 目录名与前置元数据 `name` 一致

✅ **YAML前置元数据**：
- [ ] 第一行是 `---`
- [ ] 内容前有关闭 `---`
- [ ] 有效的 YAML（无制表符，缩进正确）
- [ ] `name` 符合命名规则
- [ ] `description` 具体且不超过1024字符

✅ **内容质量**：
- [ ] 为 Claude 提供清晰的指导
- [ ] 包含具体示例
- [ ] 处理边界情况
- [ ] 列出依赖项（如有）

✅ **测试**：
- [ ] 描述与用户问题匹配
- [ ] 技能在相关查询时激活
- [ ] 指导清晰且可执行

### 步骤9：测试技能

1. **重启 Claude Code**（如已运行）以加载技能

2. **提出相关问题**（匹配描述）：

你能帮我从这个PDF中提取文本吗？


3. **验证激活**：Claude 应自动使用该技能

4. **检查行为**：确认 Claude 正确遵循指导

### 步骤10：必要时调试

若 Claude 未使用技能：

1. **让描述更具体**：
- 添加触发词
- 包含文件类型
- 提及常见用户短语

2. **检查文件位置**：
```bash
ls ~/.claude/skills/skill-name/SKILL.md
ls .claude/skills/skill-name/SKILL.md

验证 YAML：
```
cat SKILL.md | head -n 10
```
运行调试模式：
```
claude --debug
```

常见模式

只读技能

---
name: code-reader
description: 读取并分析代码但不修改。用于代码审查、理解代码库或文档编写。
allowed-tools: Read, Grep, Glob
---

基于脚本的技能

---
name: data-processor
description: 使用Python脚本处理CSV和JSON数据文件。当分析数据文件或转换数据集时使用。
---

# 数据处理器

## 使用说明

1. 使用处理脚本：
```bash
python scripts/process.py input.csv --output results.json

验证输出：

python scripts/validate.py results.json


### 支持渐进式披露的多文件技能

```yaml
---
name: api-designer
description: 遵循最佳实践设计REST API。当创建API端点、设计路由或规划API架构时使用。
---

# API设计器

快速开始：请参考 [examples.md](examples.md)

详细参考：请参考 [reference.md](reference.md)

## 使用说明

1. 收集需求
2. 设计端点（见 examples.md）
3. 用OpenAPI规范文档化
4. 对照最佳实践审查（见 reference.md）

技能作者最佳实践

单一技能单一目标：避免创建巨型技能
描述具体化：包含用户可能使用的触发词
指导清晰化：为 Claude 而非人类编写
示例具体化：提供真实代码而非伪代码
列出依赖项：在描述中提及所需包
团队测试：验证激活效果和清晰度
技能版本化：记录内容变更
渐进式披露：将高级细节放在单独文件中

验证清单

最终确定技能前，请验证：

故障排除

技能未激活：

让描述更具体（添加触发词、文件类型、用户短语）
检查文件位置
验证 YAML 格式
运行调试模式

多技能冲突：

让描述更独特
使用不同触发词
缩小每个技能的范围

技能报错：

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

示例

完整示例请参考文档：

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

输出格式

创建技能时，我将：

询问关于范围和需求的澄清问题
建议技能名称和存储位置
创建含正确前置元数据的 SKILL.md 文件
包含清晰的指导和示例
按需添加支持文件
提供测试指导
对照所有要求验证

最终结果将是一个完整、可用的技能，符合所有最佳实践和验证规则。

技能撰写师

预览