name

skill-writer

description

指导用户为 Claude Code 创建系统级 Agent Skills，支持多个业务子 Skill 的模块化设计。当用户想要创建、编写或设计系统级 Skill，或提到"生成 skills-list / 更新技能清单 / generate_skills_list"时使用。脚本 `scripts/generate_skills_list.py` 仅存放于本 skill-writer 目录，其他系统级 Skill 不需要复制；需要更新清单时由 skill-writer 脚本对目标 Skill 目录执行。

系统级 Skill 编写助手

此 Skill 帮助您为 Claude Code 创建结构良好、模块化、可扩展的系统级 Agent Skills，支持多个业务子 Skill 的集成，遵循渐进式披露、关注点分离和可组合性原则。

何时使用此 Skill

当您需要进行以下操作时使用此 Skill：

创建一个新的系统级 Agent Skill，支持多个业务子 Skill
编写或更新系统级 SKILL.md 文件，包括技能清单自动化
针对指定的系统级 Skill 生成或更新 skills-list.md（例如用户说“把这个 Skill 的 skills-list 生成一下/更新一下”）
设计系统架构、frontmatter 和子 Skill 结构
排除系统级 Skill 发现（discovery）问题的故障
将现有的提示词 (prompts) 或复杂工作流转换为模块化的系统级 Skills

指南

第 1 步：确定系统级 Skill 范围

首先，理解系统级 Skill 应该做什么：

提出澄清性问题：
- 这个系统级 Skill 应该提供什么整体能力？（例如，企业级综合管理系统）
- 它包含哪些业务子 Skill？（例如，finance、hr、it）
- Claude 应该在什么时候使用这个系统级 Skill，以及如何路由到子 Skill？
- 它需要什么工具、资源或自动化脚本？
- 这是供个人使用还是团队共享？
保持专注：一个系统级 Skill = 一个领域 + 多个可组合子 Skill
- 好： "企业级综合管理系统"（包含 finance-module、hr-module 等）
- 太宽泛： "所有业务处理"、"通用工具"

第 2 步：选择系统级 Skill 位置

确定在哪里创建系统级 Skill： 项目 Skills (.claude/skills/)：

团队工作流和公约
项目特定的领域知识
共享模块化系统（提交到 git）

第 3 步：创建系统级 Skill 结构

创建目录和文件，支持模块化设计：

# 项目
mkdir -p .claude/skills/system-name

对于系统级 Skills（注意：脚本 generate_skills_list.py 集中存放在 skill-writer/scripts/，其他 Skill 不需要复制）：

system-name/
├── SKILL.md (必须，系统入口)
├── skills-list.md (必须，技能清单；由 skill-writer 脚本生成)
├── reference.md (可选，详细业务知识)
└── modules/
    ├── sub-skill1/
    │   ├── SKILL.md (必须)
    │   ├── reference.md (可选)
    │   └── examples.md (可选)
    ├── sub-skill2/
    │   ├── SKILL.md (必须)
    │   ├── reference.md (可选)
    │   └── examples.md (可选)
    └── templates/
        └── template.txt (可选)

第 4 步：编写 SKILL.md frontmatter

创建包含必填字段的 YAML frontmatter：

---
name: system-name
description: 简要描述系统功能、包含的子 Skill 以及何时使用它
---

字段要求：

name (名称):
- 仅限小写字母、数字、连字符
- 最多 64 个字符
- 必须与目录名称匹配
- 好： enterprise-system, business-automation
- 坏： Enterprise_System, Business Tools!
description (描述):
- 最多 1024 个字符
- 包含系统做什么、包含的子 Skill 以及何时使用
- 使用用户可能会说的具体触发词
- 提及路由流程、子模块和上下文

可选 frontmatter 字段：

allowed-tools: 限制工具访问（逗号分隔列表）
```
allowed-tools: Read, Grep, Glob, Bash
```
用于：
- 系统级路由和子 Skill 执行
- 安全敏感的工作流
- 范围受限的操作

第 5 步：编写有效的描述

描述对于 Claude 发现您的系统级 Skill 至关重要。

公式: [系统做什么] + [何时使用] + [关键触发词] + [子 Skill 概述]

示例:

✅ 好:

description: 企业级综合管理系统，处理财务、HR 和 IT 业务。优先查阅 ./skills-list.md 以路由到子模块，如费用报销或员工入职。当用户提到企业管理、报销或人事时使用。

✅ 好:

description: 项目自动化系统，集成代码审查、文档生成和测试模块。当处理项目工作流、代码分析或自动化测试时使用，路由至相应子 Skill。

❌ 太模糊:

description: 帮助处理业务
description: 用于系统管理

提示:

包含具体的子模块名称 (finance-module, hr-module)
提及常见的用户短语（"报销"、"入职"、"查询"）
列出具体的操作和路由（而不是通用的动词）
添加上下文线索（"Use when..."，"Route to..."）

第 6 步：构建系统级 Skill 内容

使用清晰的 Markdown 章节，支持渐进式披露：

# 系统名称

简要概述此系统级 Skill 的功能和子 Skill 集成。

## Quick start (快速开始)

提供一个简单的路由例子以便立即上手。

## Instructions (说明)

给 Claude 的分步指导：
1. 阅读 ./skills-list.md 获取子 Skill 清单
2. 根据用户需求匹配并路由到子 Skill
3. 执行子 Skill 的核心指令
4. 处理边缘情况，如子 Skill 冲突

## Examples (示例)

显示包含路由和子 Skill 执行的具体使用示例。

## Best practices (最佳实践)

- 需遵循的关键公约（如模块化设计）
- 需避免的常见陷阱（如上下文过载）
- 何时使用系统级 vs 子 Skill

## Requirements (要求)

列出任何依赖项或先决条件：
```bash
pip install pyyaml

Advanced usage (高级用法)

对于复杂场景，请参阅 reference.md。


### 第 7 步：添加辅助文件（必须/可选）

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

**skills-list.md**: 自动化生成的子 Skill 清单（必须）
**reference.md**: 详细的业务知识和高级选项（可选）
**modules/**: 子 Skill 目录，每个包含自己的 SKILL.md（必须），以及 reference.md 和 examples.md（可选）
**templates/**: 文件模板或样板代码（可选）

从 SKILL.md 引用它们：
```markdown
先阅读 [skills-list.md](skills-list.md) 以确定子模块。

运行自动化脚本：
\`\`\`bash
python scripts/generate_skills_list.py
\`\`\`

对于子 Skill，从子 SKILL.md 引用辅助文件：

有关高级用法，请参阅 [reference.md](reference.md)。

查看示例，请参阅 [examples.md](examples.md)。

第 8 步：实现技能清单自动化

脚本 `scripts/generate_skills_list.py` 仅存放在 skill-writer 目录，其他系统级 Skill 不需要复制该脚本。

脚本接受一个可选的命令行参数 --target，指定目标系统级 Skill 的根目录（绝对或相对路径）。如果不传，则默认扫描脚本自身所在 Skill（即 skill-writer）。

skills-list.md 输出为 XML 风格列表，每个子 Skill 一个 <skill>：

<name>：子 Skill 的 frontmatter name
<description>：子 Skill 的 frontmatter description
<location>：固定为 project
<relativePath>：相对系统级根目录的子 Skill 目录路径（例如 modules/echo）

调用示例

为指定 Skill 生成/更新清单（推荐）：

python "<skill-writer-dir>\scripts\generate_skills_list.py" --target "<path-to-target-skill>"

例如：

python "D:\Desktop\03 Code\agent-skills\.claude\skills\skill-writer\scripts\generate_skills_list.py" --target "D:\Desktop\03 Code\agent-skills\.claude\skills\test-skill"

如果用户要求帮忙生成/更新某 Skill 的清单：

确认目标 Skill 目录名或绝对路径（例如 test-skill 或完整路径）。
在 .claude/skills/ 下按目录名定位目标：
- 若能唯一匹配：继续
- 若不唯一/不清晰：要求用户提供目标目录的绝对路径
调用 skill-writer/scripts/generate_skills_list.py --target <目标路径>，覆盖更新目标 Skill 的 skills-list.md。

集成到 CI/CD 或 pre-commit 钩子以保持更新。

第 9 步：验证系统级 Skill

检查这些要求：

✅ 文件结构:

SKILL.md 和 skills-list.md 存在于正确的位置
目录名称与 frontmatter 中的 name 匹配
子模块在 modules/ 下，每个有 SKILL.md，并可选有 reference.md 和 examples.md

✅ YAML frontmatter:

第 1 行包含开头的 ---
内容之前包含结尾的 ---
有效的 YAML（无制表符，缩进正确）
name 遵循命名规则
description 具体且少于 1024 个字符

✅ 内容质量:

路由说明清晰
提供了子 Skill 示例
处理了冲突和边缘情况
自动化脚本工作正常
子 Skill 的辅助文件（如 reference.md、examples.md）正确引用

✅ 测试:

描述与用户问题匹配
系统在相关查询时激活并路由
子 Skill 正确加载，包括可选文件

第 10 步：测试系统级 Skill

重启 Claude Code（如果正在运行）以加载系统

提出相关问题以匹配描述：

Can you handle expense reimbursement in the enterprise system?
（你能处理企业系统中的费用报销吗？）

验证激活：Claude 应该阅读 skills-list.md 并路由到子 Skill
检查行为：确认 Claude 正确遵循路由和子 Skill 说明，包括加载可选的 reference.md 或 examples.md 如果需要

第 11 步：根据需要进行调试

如果 Claude 没有正确路由或加载子文件：

使描述更具体：
- 添加触发词和子模块关键词
- 包含文件类型和操作

检查文件位置：

ls ~/.claude/skills/system-name/SKILL.md
ls .claude/skills/system-name/SKILL.md

验证 YAML 和脚本:

cat SKILL.md | head -n 10
python scripts/generate_skills_list.py

运行调试模式:
```
claude --debug
```

常见模式

路由型系统级 Skill

---
name: enterprise-system
description: 企业级综合管理系统。请优先查阅 ./skills-list.md 以确定调用哪个子模块。
allowed-tools: Read, Grep, Glob, Bash
---

基于脚本的系统级 Skill

---
name: automation-hub
description: 项目自动化中心，集成多个子模块。当自动化工作流时使用，路由至子 Skill。
---

# Automation Hub

## Instructions

1. 执行 ./scripts/generate_skills_list.py 更新清单
2. 阅读 ./skills-list.md
3. 路由到匹配子模块

具有渐进式披露的多模块系统

---
name: business-suite
description: 业务套件系统，支持财务、HR 等模块。当处理业务场景时使用。
---

# Business Suite

快速开始：参见 [skills-list.md](skills-list.md)

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

## Instructions

1. 收集需求
2. 匹配子模块（参见 skills-list.md）
3. 执行子 Skill
4. 集成结果

子 Skill 作者的最佳实践

模块化设计：每个子 Skill 一个目的，避免系统过载
具体的描述：包含触发词和路由线索
清晰的路由：为 Claude 写路由流程，不是为人
自动化维护：使用脚本保持清单更新
列出依赖项：在系统和子 Skill 中提及所需的包
与队友一起测试：验证路由和清晰度
版本化您的系统：在内容中记录变更
使用渐进式披露：将细节放在单独的文件中，如 reference.md 和 examples.md

验证检查清单

在最终确定系统级 Skill 之前，请验证：

名称仅包含小写字母、连字符，最多 64 个字符
描述具体且少于 1024 个字符
描述包含 "what"（什么）、"when"（何时）和路由
YAML frontmatter 有效
路由说明是分步骤的
子 Skill 示例具体且真实
自动化脚本和依赖项已记录
文件路径使用正斜杠
系统在相关查询时激活并路由
Claude 正确遵循说明
子 Skill 的可选文件（如 reference.md、examples.md）正确配置和引用

故障排除

系统未激活或未路由:

使用触发词使描述更具体
在描述中包含子模块和操作
添加带有用户短语的 "Route when..."（当...时路由）子句

子 Skill 冲突:

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

维护问题:

检查 YAML 语法（无制表符，缩进正确）
验证脚本执行权限
确保 CI/CD 集成自动化更新

可选文件未加载:

确认子 Skill 目录中文件路径正确
在子 SKILL.md 中使用相对路径引用（如 reference.md）
测试 Claude 是否在需要时加载这些文件

示例

查看完整示例的文档：

简单的路由系统 (enterprise-system)
具有工具权限的系统 (automation-hub)
多模块系统 (business-suite)，包含子 Skill 的 reference.md 和 examples.md

输出格式

当创建系统级 Skill 时，我将：

询问关于范围、子 Skill 和需求的澄清性问题
建议系统名称、位置和架构
创建带有正确 frontmatter 的 SKILL.md 文件
包含自动化脚本和技能清单
添加子 Skill 模块，包括可选的 reference.md 和 examples.md
提供测试和路由说明
根据所有要求进行验证

结果将是一个完整、可工作的系统级 Skill，遵循所有最佳实践、模块化原则和验证规则。

Install Skill

SKILL.md