AI Skills
skill-writer

skill-writer

热门

引导用户为 Claude Code 创建 Agent Skill。当用户想要创建、撰写、设计新 Skill，或者在 SKILL.md 文件、frontmatter 配置、Skill 目录结构上需要帮助时使用。

10万Star
2.9万Fork
更新于 2026/7/31
获取 Skill源代码

相关 Skills

contract-first24万camsnap38万fsharp-testing24万
SKILL.md
只读
名称
skill-writer
描述

引导用户为 Claude Code 创建 Agent Skill。当用户想要创建、撰写、设计新 Skill，或者在 SKILL.md 文件、frontmatter 配置、Skill 目录结构上需要帮助时使用。

Skill Writer

本 Skill 旨在帮助你为 Claude Code 打造结构规范、符合最佳实践与校验要求的 Agent Skill。

何时使用本 Skill

在以下场景中使用本 Skill：

  • 创建新的 Agent Skill
  • 编写或更新 SKILL.md 文件
  • 设计 Skill 目录结构和 frontmatter 配置
  • 排查 Skill 无法被识别/发现的问题
  • 将现有的 Prompt 或工作流转化为 Skill

操作指南

第一步：明确 Skill 的作用域

首先，要搞清楚这个 Skill 究竟要解决什么问题：

  1. 先问清楚这几个问题：

    • 这个 Skill 要提供什么具体能力？
    • Claude 应该在什么场景下触发/使用这个 Skill？
    • 它需要用到哪些工具或资源？
    • 它是个人自用，还是团队共享？

  2. 保持聚焦：一个 Skill 只做一件事

    • 推荐（聚焦）："PDF 表单填写"、"Excel 数据分析"
    • 不推荐（太宽泛）："文档处理"、"数据工具"

第二步：选择 Skill 存放位置

确定在哪里创建该 Skill：

个人级别 Skill (~/.claude/skills/)：

  • 个人专属的工作流与偏好设置
  • 实验性质的 Skill
  • 个人效率工具

项目级别 Skill (.claude/skills/)：

  • 团队统一的工作流与规范
  • 项目专属的领域知识
  • 共享工具集（需提交至 git）

第三步：创建 Skill 目录结构

创建对应的目录和文件：

# 个人级别
mkdir -p ~/.claude/skills/skill-name

# 项目级别
mkdir -p .claude/skills/skill-name

多文件 Skill 结构示例：

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

第四步：编写 SKILL.md 的 frontmatter

在文件顶部添加 YAML frontmatter，并填入必要字段：

---
name: skill-name
description: 简要说明这个 Skill 的功能以及何时使用它
---

字段要求：

  • name：

    • 仅限小写字母、数字和连字符（-）
    • 最长 64 个字符
    • 必须与目录名称保持一致
    • 推荐：pdf-processor、git-commit-helper
    • 不推荐：PDF_Processor、Git Commits!

  • description：

    • 最长 1024 个字符
    • 必须同时包含功能说明和使用场景
    • 使用用户可能会说的具体触发词
    • 提及相关的文件类型、具体操作和上下文信息

可选 frontmatter 字段：

  • allowed-tools：限制可用的工具（以逗号分隔）
    allowed-tools: Read, Grep, Glob
    适用于：
    • 只读类型的 Skill
    • 安全敏感型工作流
    • 受限范围的操作

第五步：撰写高效的 description

description 对于 Claude 能否精准识别并激活你的 Skill 至关重要。

撰写公式：[功能说明] + [使用场景] + [核心触发词]

示例：

✅ 优秀示例：

description: 提取 PDF 文件中的文本与表格、填写表单、合并文档。在处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。

✅ 优秀示例：

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

❌ 过于模糊（不推荐）：

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

小贴士：

  • 包含具体的文件扩展名（如 .pdf、.xlsx、.json）
  • 加上用户常用的表达方式（如“分析”、“提取”、“生成”）
  • 列出具体的动作/操作（避免使用笼统泛泛的动词）
  • 加上场景提示词（如 "Use when..."、"For..."）

第六步：组织 Skill 正文结构

使用清晰的 Markdown 标题层级划分内容：

# Skill 名称

简要概述这个 Skill 的核心功能。

## 快速上手

提供一个简单的示例，方便立即体验和上手。

## 操作指南

给 Claude 步骤清晰的指引：
1. 第一步：明确的操作指令
2. 第二步：预期达成的结果
3. 边界情况的处理方式

## 使用示例

展示具体的实际使用案例，附带代码或命令行示例。

## 最佳实践

- 需要遵循的核心规范
- 需要避开的常见坑点
- 适用场景与不适用场景

## 环境与依赖

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

进阶用法

复杂场景下的高级用法，请参阅 reference.md。


#### 第七步：添加辅助文件（可选）

根据按需加载（Progressive Disclosure）原则创建补充文件：

**reference.md**：详细的 API 文档、高级配置选项
**examples.md**：丰富的补充示例和场景用例
**scripts/**：辅助脚本和实用工具
**templates/**：文件模板或脚手架

在 SKILL.md 中进行引用：
```markdown
如需了解进阶用法，请参阅 [reference.md](reference.md)。

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

第八步：校验 Skill 配置

对照检查以下各项指标：

✅ 目录结构：

  • [ ] SKILL.md 存在于正确的路径下
  • [ ] 目录名与 frontmatter 中的 name 一致

✅ YAML frontmatter：

  • [ ] 第 1 行以 --- 开头
  • [ ] 正文前以 --- 结尾
  • [ ] 格式符合 YAML 规范（不得使用制表符 Tab，缩进正确）
  • [ ] name 符合命名规范
  • [ ] description 描述具体，且字数不超过 1024 字符

✅ 内容质量：

  • [ ] 为 Claude 提供了清晰易懂的操作指令
  • [ ] 附带了真实的具体示例
  • [ ] 考虑并处理了边界情况
  • [ ] 明确标注了所需依赖（如有）

✅ 激活测试：

  • [ ] description 匹配用户的提问习惯
  • [ ] Skill 能在相关查询中被正常激活
  • [ ] 操作指令清晰、可执行

第九步：测试 Skill

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

  2. 提出与 description 匹配的相关问题：

    你能帮我提取这个 PDF 里的文本吗？

  3. 验证是否成功激活：Claude 应该会自动调用该 Skill

  4. 检查执行效果：确认 Claude 能否准确遵循指令完成任务

第十步：排查与调试（必要时）

如果 Claude 没有自动使用该 Skill：

  1. 让 description 更加具体：

    • 补充更多触发词
    • 明确标注文件类型
    • 加入用户常用的口语表达

  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: 读取并分析代码，但不做修改。用于代码审查、理解代码库或编写文档。
allowed-tools: Read, Grep, Glob
---

结合脚本的 Skill

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

# Data Processor

## 操作指南

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

2. 校验输出结果：
\`\`\`bash
python scripts/validate.py results.json
\`\`\`

按需分层加载的多文件 Skill

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

# API Designer

快速上手：参阅 [examples.md](examples.md)

详细参考文档：参阅 [reference.md](reference.md)

## 操作指南

1. 收集并梳理需求
2. 设计 API Endpoint（参见 examples.md）
3. 编写 OpenAPI 规范文档
4. 对照最佳实践进行审查（参见 reference.md）

Skill 开发者最佳实践

  1. 一个 Skill 只做一件事：切忌打造臃肿的“万能 Skill”
  2. 描述一定要精准：尽可能覆盖用户提问时会用到的关键词
  3. 指令清晰明确：这些指引是写给 Claude 看的，要直接、干脆
  4. 提供真实的示例：给真实的代码或命令，不要用伪代码
  5. 明确列出依赖：在 description 里注明需要的依赖包
  6. 找队友帮忙实测：验证触发激活率和实际使用体验
  7. 做好版本维护：在文档中记载更新记录
  8. 合理利用按需分层：把高级配置和复杂细节拆分到单独文件中

校验清单

在最终定稿 Skill 前，请逐项核对：

  • [ ] 名称全小写、仅使用连字符，不超过 64 个字符
  • [ ] description 描述具体，不超过 1024 个字符
  • [ ] description 明确包含了“干什么”和“何时用”
  • [ ] YAML frontmatter 语法合法
  • [ ] 操作指令步骤清晰、条理分明
  • [ ] 示例真实具体，贴近实际使用场景
  • [ ] 依赖项已完整列出
  • [ ] 文件路径均统一使用正斜杠 /
  • [ ] 能在相关提问中顺畅激活
  • [ ] Claude 能严格按照指令正常工作

故障排查

Skill 无法激活：

  • 在 description 中补充更多具体的触发词
  • 在 description 里加上文件扩展名和操作动作
  • 明确加上带用户真实口吻的 "Use when..." 句式

多个 Skill 发生冲突：

  • 区分各 Skill 的 description，避免语义重叠
  • 使用互不相同的触发词
  • 进一步收紧每个 Skill 的作用边界

Skill 运行报错：

  • 检查 YAML 语法（是否有 Tab 缩进问题）
  • 检查文件路径（必须使用正斜杠 /）
  • 确保脚本文件具备可执行权限
  • 补充齐备所有必需的依赖包

示例参考

完整示例可参阅相关官方文档：

  • 单文件简易 Skill (commit-helper)
  • 带工具权限控制的 Skill (code-reviewer)
  • 多文件复杂 Skill (pdf-processing)

输出规范

在帮助你创建 Skill 时，我会：

  1. 针对作用域和具体需求提出针对性问题
  2. 建议合适的 Skill 名称和存放位置
  3. 生成带有标准 frontmatter 配置的 SKILL.md 文件
  4. 编写清晰的操作步骤与使用示例
  5. 按需补充辅助文件
  6. 提供详细的测试步骤
  7. 对照各项校验规则进行核验

最终产出的将是一个完全符合最佳实践与校验规范、开箱即用的完整 Agent Skill。