Skill creator gd

Skill 开发制作指导

Skill 创建/修改遵循以下工作流，确保输出合规。

第一步：需求确认

向用户确认以下信息（若用户已充分描述则跳过）：

1. 目的：解决什么问题？什么场景下触发？
2. 类型：
   • 引用型：提供知识、规范、模式（如编码规范、设计模式库）
   • 任务型：执行具体操作（如部署、提交、生成代码）
3. 范围：个人级（~/.claude/skills/）、项目级（.claude/skills/）、插件级？
4. 副作用：是否涉及部署、推送、发送消息等不可逆操作？

第二步：Frontmatter 设计

SKILL.md 必须以 --- 包裹的 YAML frontmatter 开头。

必需字段

description: 功能与触发时机的描述。首个用例放最前面，包含用户自然表达的关键词

按需字段速查

场景	字段	值
有副作用（部署/发送）	disable-model-invocation	true
纯背景知识，不需手动触发	user-invocable	false
需隔离执行	context	fork
指定子代理类型	agent	Explore / Plan / 自定义
预授权工具	allowed-tools	Bash(git add *) Bash(git commit *)
接受参数	arguments	[issue, priority]
参数提示	argument-hint	[issue-number]
限制文件范围	paths	["src/**/*.tsx"]
覆盖模型	model	sonnet / opus / inherit
覆盖 effort	effort	low / medium / high

格式约束

• name：仅小写字母、数字、连字符，最长 64 字符。省略则用目录名
• description + when_to_use：合计上限 1,536 字符
• name 省略时自动取目录名，显式声明更清晰

第三步：正文编写

核心原则

• 精简：控制在 500 行以内，每一行都是持续 token 成本
• 直接：陈述"做什么"，不叙述"为什么"或"怎么做"
• 结构化：用标题和列表组织，避免大段散文
• 按需引用：大段参考材料、详细示例移至辅助文件

正文结构建议

# Skill 名称

1-2 句概述

---

## 主题一（规则/步骤/知识要点）

## 主题二

## 参考资源（链接到辅助文件）

关于模板使用

templates.md 提供各类型模板，格式符合最佳规范。模板仅作参考，按实际需求调整。硬填导致能力漂移。

语言表达规范

Skill 正文每行持续占用 token，确保信息密度高。

核心判据：每个词都问"去掉后命题内容是否改变？"不变则删。

词汇精简（8类冗余消除）

类	目标词	操作	示例
虚词	的/了/进行/加以/予以	默认删，仅歧义保留	系统的功能→系统功能；进行了检测→检测
回指	系统/程序/该模块/本机制/本功能	删可推断的回指词	该模块处理→处理；本机制提供→提供
框定	所谓的/相应的/一定的/相关的	删无信息修饰语	相应的处理→处理
限定	特定/相应/适当的	不影响精确度时删	特定的条件→条件
量词	一个/一次/一种	不影响精确度时删	一个回调→回调
名词化	对X进行Y	→直接动宾	对数据进行检测→检测数据
框架词	在…情况下/通过…来实现	紧凑化	在超时情况下→超时时
从句	X所对应的Y	删"所"结构	文件所对应的路径→文件路径

句法紧凑化

• 允许合并：连动因果链（检测触发处理）、条件→结果（超时后重试）
• 必须拆分：独立事件无逻辑关联、主语转换
• 条件紧凑化：当X满足条件Y时执行Z → X满足Y时执行Z
• 重复主语省略：UITask管理生命周期。UITask协调组件。 → UITask管理生命周期，协调组件。

句首领域名词

句首必须是领域实体名词，禁止：

• 回指壳：程序/系统/该功能/本模块
• 主题标记：关于/对于/至于
• 元叙述：模块的作用是/功能提供

例外：需区分多个主体时可保留标识。

结构性优化

• 列表 ≤3项且每项 ≤30字 → 行内合并
• 5个以下并列项无子项 → 单行分隔
• 总结性复述（"含义：""即："后与前文重复）→ 强制删除
• 同义重述、因果重复 → 只保留一处

动态上下文注入

需要实时数据时使用 !`command` 语法，在发送给 Claude 前执行 shell 命令：

## 当前变更
!`git diff HEAD`

• ! 必须出现在行首或紧跟空白之后
• 替换只运行一次，输出不会再被扫描
• 多行命令用围栏代码块：

```!
git status --short
git log --oneline -5

### 变量替换

| 变量                     | 用途                    |
| ---------------------- | --------------------- |
| `$ARGUMENTS`           | 所有传入参数                |
| `$0` / `$1`            | 按索引访问参数（0-based）      |
| `$name`                | `arguments` 字段声明的命名参数 |
| `${CLAUDE_SKILL_DIR}`  | SKILL.md 所在目录的绝对路径    |
| `${CLAUDE_SESSION_ID}` | 当前会话 ID               |
| `${CLAUDE_EFFORT}`     | 当前 effort 级别          |

### 引用辅助文件和脚本

辅助文件 Markdown 链接引用，脚本用 `${CLAUDE_SKILL_DIR}` 定位（自动解析为 SKILL.md 所在目录）：

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

python3 ${CLAUDE_SKILL_DIR}/scripts/your-script.py

第四步：合规检查

输出 SKILL.md 前，逐项验证：

• 文件以 --- 包裹的 YAML frontmatter 开头
• frontmatter 包含 description 字段
• description 包含用户自然表达的关键词，首个用例在前
• description + when_to_use ≤ 1,536 字符
• name 仅含小写字母、数字、连字符，≤ 64 字符
• 有副作用的操作设了 disable-model-invocation: true
• 正文 ≤ 500 行
• 脚本路径使用 ${CLAUDE_SKILL_DIR} 而非硬编码
• 辅助文件通过相对路径引用
• 参数引用使用 $ARGUMENTS 或命名参数
• 正文无模板残留内容（检查是否存在与实际 Skill 目的无关的模板框架文本）
• 正文无语法冗余（逐段检查8类词汇冗余、句法冗余、句首回指壳）

第五步：创建辅助文件（按需）

正文需要大量参考材料时创建：

skill-name/
├── SKILL.md           # 主文件（精简）
├── reference.md       # 详细参考文档
├── templates.md       # 模板和示例
└── scripts/           # 工具脚本
    └── helper.py

从 SKILL.md 中明确说明每个辅助文件的用途和加载时机。

第六步：输出

1. 输出完整文件内容，包含所有辅助文件
2. 说明建议的存放路径（~/.claude/skills/<name>/ 或 .claude/skills/<name>/）
3. 提示用户可通过 /skill-name 测试调用

---

常见错误速查

错误	表现	修正
缺少 frontmatter	整个文件被当作正文，skill 无法正确识别	必须添加 --- 包裹的 YAML 头
description 在正文中	标题被当作描述，触发匹配不准	description 只写在 YAML frontmatter 中
正文首行是描述文字	重复信息浪费 token	描述仅在 frontmatter，正文直接开始指令
name 含大写/空格/特殊字符	调用失败或行为异常	仅用小写字母、数字、连字符
正文过长	占满上下文预算，被压缩丢弃	≤ 500 行，大段内容放辅助文件
硬编码绝对路径	迁移后路径失效	使用 ${CLAUDE_SKILL_DIR}
副作用操作未限制自动调用	Claude 意外执行部署等操作	设 disable-model-invocation: true
description 过于笼统	触发不准（过多或不触发）	包含用户自然说的关键词，首个用例前置
正文写教程而非指令	Claude 读到知识但不执行	写指令："做X"，不是"X是Y"
模板内容残留	Skill 执行了与目标无关的动作（能力漂移）	模板仅作参考，必须按实际需求调整内容，删除不相关的模板框架
正文语法冗余	虚词/回指/框架词浪费 token，降低指令密度	按8类词汇冗余检查表逐段清理（见"语言表达规范"）

详细参考

• 完整字段说明、作用域、生命周期见 reference.md
• 各类型 Skill 模板见 templates.md