claude-skills

Claude Skills 元技能

将零散的领域材料转化为可复用、易维护且能可靠触发的 Skill：

• SKILL.md 作为入口文件（触发条件、约束、模式、示例）
• references/ 用于存放长篇证据和导航内容
• 可选的 scripts/ 和 assets/ 用于脚手架和模板

何时使用此 Skill

在以下情况下，触发此元技能：

• 根据文档／规范／代码仓库从零创建新的 Skill
• 重构现有 Skill（过长、含糊、不一致或触发失灵）
• 设计可靠的触发机制（frontmatter + 触发条件 + 边界）
• 从大量材料中提取简明速查表
• 将长篇内容拆分到便于导航的 references/ 中
• 添加质量门禁和验证器

不适用场景／边界

此元技能不属于以下情况：

• 本身就是一个领域 Skill（它用于构建领域 Skill）
• 允许编造外部事实（如果材料无法证明某事，就应明确说明，并添加验证途径）
• 可替代必需输入（如果缺少输入，请先提出 1-3 个问题，再继续）

速查表

交付内容（必须产出什么）

你的输出必须包括：

1. 具体的目录结构（通常为 skills/<skill-name>/）
2. 可执行的 SKILL.md，包含可判定的触发条件、边界和可复现示例
3. 移至 references/ 的长篇文档，以及 references/index.md
4. 交付前检查清单（质量门禁）

推荐布局（从精简到完整）

skill-name/
|-- SKILL.md              # Required: entrypoint with YAML frontmatter
|-- references/           # Optional: long-form docs/evidence/index
|   `-- index.md          # Recommended: navigation index
|-- scripts/              # Optional: helpers/automation
`-- assets/               # Optional: templates/configs/static assets

真正的最简版本只有 SKILL.md（之后可以添加 references/）。

YAML Frontmatter（必需）

---
name: skill-name
description: "What it does + when to use (activation triggers)."
---

Frontmatter 规则：

• name 必须匹配 ^[a-z][a-z0-9-]*$，且应与目录名一致
• description 必须可判定（不能只写“帮助处理 X”），并包含具体的触发关键词

最简 SKILL.md 骨架（复制／粘贴）

---
name: my-skill
description: "[Domain] capability: includes [capability 1], [capability 2]. Use when [decidable triggers]."
---

# my-skill Skill

One sentence that states the boundary and the deliverable.

## When to Use This Skill

Trigger when any of these applies:
- [Trigger 1: concrete task/keyword]
- [Trigger 2]
- [Trigger 3]

## Not For / Boundaries

- What this skill will not do (prevents misfires and over-promising)
- Required inputs; ask 1-3 questions if missing

## Quick Reference

### Common Patterns

**Pattern 1:** one-line explanation
```text
[command/snippet you can paste and run]

示例

示例 1

• 输入：
• 步骤：
• 预期输出／验收标准：

示例 2

示例 3

参考资料

• references/index.md：导航
• references/...：按主题拆分的长篇文档

维护

• 来源：文档／代码仓库／规范（不得编造）
• 最后更新：YYYY-MM-DD
• 已知限制：明确列出不在范围内的内容

### Authoring Rules (Non-negotiable)

1. Quick Reference is for short, directly usable patterns
   - Keep it <= 20 patterns when possible.
   - Anything that needs paragraphs of explanation goes to `references/`.
2. Activation must be decidable
   - Frontmatter `description` should say "what + when" with concrete keywords.
   - "When to Use" must list specific tasks/inputs/goals, not vague help text.
   - "Not For / Boundaries" is mandatory for reliability.
3. No bluffing on external details
   - If the material does not prove it, say so and include a verification path.

### Workflow (Material -> Skill)

Do not skip steps:
1. Scope: write MUST/SHOULD/NEVER (three sentences total is fine)
2. Extract patterns: pick 10-20 high-frequency patterns (commands/snippets/flows)
3. Add examples: >= 3 end-to-end examples (input -> steps -> acceptance)
4. Define boundaries: what is out-of-scope + required inputs
5. Split references: move long text into `references/` + write `references/index.md`
6. Apply the gate: run the checklist and the validator

### Quality Gate (Pre-delivery Checklist)

Minimum checks (see `references/quality-checklist.md` for the full version):
1. `name` matches `^[a-z][a-z0-9-]*$` and matches the directory name
2. `description` states "what + when" with concrete trigger keywords
3. Has "When to Use This Skill" with decidable triggers
4. Has "Not For / Boundaries" to reduce misfires
5. Quick Reference is <= 20 patterns and each is directly usable
6. Has >= 3 reproducible examples
7. Long content is in `references/` and `references/index.md` is navigable
8. Uncertain claims include a verification path (no bluffing)
9. Reads like an operator's manual, not a documentation dump

Validate locally:

```bash
# From repo root (basic validation)
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name>

# From repo root (strict validation)
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name> --strict

# From skills/claude-skills/ (basic validation)
./scripts/validate-skill.sh ../<skill-name>

# From skills/claude-skills/ (strict validation)
./scripts/validate-skill.sh ../<skill-name> --strict

工具和模板

生成新的 Skill 骨架：

# From repo root (generate into ./skills/)
./skills/claude-skills/scripts/create-skill.sh my-skill --full --output skills

# From skills/claude-skills/ (generate into ../ i.e. ./skills/)
./scripts/create-skill.sh my-skill --full --output ..

# Minimal skeleton
./skills/claude-skills/scripts/create-skill.sh my-skill --minimal --output skills

模板：

• assets/template-minimal.md
• assets/template-complete.md

示例

示例 1：根据文档创建 Skill

• 输入：一份官方文档／规范 + 2-3 个真实代码示例 + 常见故障模式
• 步骤：
  1. 运行 create-skill.sh，搭建 skills/<skill-name>/ 的脚手架
  2. 将 frontmatter 的 description 写成“内容 + 适用时机”
  3. 将 10-20 个高频模式提取到速查表中
  4. 添加至少 3 个端到端示例，并附上验收标准
  5. 将长篇内容放入 references/，并在 references/index.md 中添加链接
  6. 运行 validate-skill.sh --strict 并反复调整

示例 2：重构“文档堆砌型” Skill

• 输入：包含大量粘贴文档的现有 SKILL.md
• 步骤：
  1. 判断哪些部分是模式，哪些是长篇说明
  2. 将长篇文本移至 references/（按主题拆分）
  3. 将速查表改写为简短、可复制／粘贴的模式
  4. 添加或修正示例，直到可以复现
  5. 添加“不适用场景／边界”，减少误触发

示例 3：验证并为 Skill 设置质量门禁

• 输入：skills/<skill-name>/
• 步骤：
  1. 运行 validate-skill.sh（非严格模式）以获取警告
  2. 修正 frontmatter／名称不匹配和缺失章节的问题
  3. 运行 validate-skill.sh --strict 以强制执行规范
  4. 发布前，运行 references/quality-checklist.md 中的评分标准

参考资料

本地文档：

• references/index.md
• references/skill-spec.md
• references/quality-checklist.md
• references/anti-patterns.md
• references/README.md（上游官方参考资料）

外部（官方）：

• https://support.claude.com/en/articles/12512176-what-are-skills
• https://support.claude.com/en/articles/12512180-using-skills-in-claude
• https://support.claude.com/en/articles/12512198-creating-custom-skills
• https://docs.claude.com/en/api/skills-guide

维护

• 来源：skills/claude-skills/references/ 中的本地规范文件，以及 references/README.md 中的上游官方文档
• 最后更新：2025-12-14
• 已知限制：validate-skill.sh 使用启发式检查；严格模式假定使用推荐的章节标题