Back to Details

claude-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Skills Meta-Skill

Claude Skills元技能

Turn scattered domain material into a Skill that is reusable, maintainable, and reliably activatable:
  • SKILL.md
    as the entrypoint (triggers, constraints, patterns, examples)
  • references/
    for long-form evidence and navigation
  • optional 
    scripts/
    and 
    assets/
    for scaffolding and templates
将零散的领域素材转换为可复用、可维护且能可靠激活的Skill：
  • SKILL.md
    作为入口文件（触发条件、约束、模式、示例）
  • references/
    用于存放长格式证据和导航内容
  • 可选的 
    scripts/
    和 
    assets/
    用于脚手架和模板

When to Use This Skill

何时使用此技能

Trigger this meta-skill when you need to:
  • Create a new Skill from scratch from docs/specs/repos
  • Refactor an existing Skill (too long, unclear, inconsistent, misfires)
  • Design reliable activation (frontmatter + triggers + boundaries)
  • Extract a clean Quick Reference from large material
  • Split long content into navigable 
    references/
  • Add a quality gate and a validator
当你需要以下操作时触发此元技能：
  • 从文档/规范/代码库从零创建新Skill
  • 重构现有Skill（过长、表述模糊、不一致、触发失效）
  • 设计可靠的激活机制（前置元数据 + 触发条件 + 边界）
  • 从大量素材中提取简洁的快速参考内容
  • 将长内容拆分到可导航的 
    references/
    目录
  • 添加质量管控机制和验证器

Not For / Boundaries

不适用场景/边界

This meta-skill is NOT:
  • A domain Skill by itself (it builds domain Skills)
  • A license to invent external facts (if the material does not prove it, say so and add a verification path)
  • A substitute for required inputs (if inputs are missing, ask 1-3 questions before proceeding)
此元技能不用于：
  • 本身作为领域Skill（它用于构建领域Skill）
  • 编造外部事实（如果素材无法证明，需说明并添加验证路径）
  • 替代必要的输入（如果输入缺失，先提出1-3个问题再继续）

Quick Reference

快速参考

Deliverables (What You Must Produce)

交付成果（必须产出）

Your output MUST include:
  1. A concrete directory layout (typically 
    skills/<skill-name>/
    )
  2. An actionable 
    SKILL.md
    with decidable triggers, boundaries, and reproducible examples
  3. Long-form docs moved to 
    references/
    with a 
    references/index.md
  4. A pre-delivery checklist (Quality Gate)
你的输出必须包含：
  1. 具体的目录结构（通常为 
    skills/<skill-name>/
    ）
  2. 可执行的 
    SKILL.md
    ，包含可判定的触发条件、边界和可复现的示例
  3. 长格式文档移至 
    references/
    目录，并附带 
    references/index.md
  4. 交付前检查清单（质量管控）

Recommended Layout (Minimal -> Full)

推荐目录结构（最简 -> 完整）

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
The truly minimal version is just 
SKILL.md
(you can add 
references/
later).
skill-name/
|-- SKILL.md              # 必填：带YAML前置元数据的入口文件
|-- references/           # 可选：长格式文档/证据/索引
|   `-- index.md          # 推荐：导航索引
|-- scripts/              # 可选：辅助工具/自动化脚本
`-- assets/               # 可选：模板/配置/静态资源
真正的最简版本仅包含 
SKILL.md
（可后续添加 
references/
）。

YAML Frontmatter (Required)

YAML前置元数据（必填）

yaml
---
name: skill-name
description: "What it does + when to use (activation triggers)."
---
Frontmatter rules:
  • name
    MUST match 
    ^[a-z][a-z0-9-]*$
    and SHOULD match the directory name
  • description
    MUST be decidable (not "helps with X") and include concrete trigger keywords
yaml
---
name: skill-name
description: "What it does + when to use (activation triggers)."
---
前置元数据规则：
  • name
    必须匹配正则 
    ^[a-z][a-z0-9-]*$
    ，且应与目录名一致
  • description
    必须是可判定的（不能是“帮助处理X”），且包含具体的触发关键词

Minimal 
SKILL.md
Skeleton (Copy/Paste)

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

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

my-skill Skill

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]
当以下任一情况适用时触发：
  • [触发条件1：具体任务/关键词]
  • [触发条件2]
  • [触发条件3]

Not For / Boundaries

不适用场景/边界

  • What this skill will not do (prevents misfires and over-promising)
  • Required inputs; ask 1-3 questions if missing
  • 此技能不会执行的操作（避免触发失效和过度承诺）
  • 必要输入；如果缺失，提出1-3个问题

Quick Reference

快速参考

Common Patterns

常见模式

Pattern 1: one-line explanation
text
[command/snippet you can paste and run]
模式1： 一行说明
text
[可复制运行的命令/代码片段]

Examples

示例

Example 1

示例1

  • Input:
  • Steps:
  • Expected output / acceptance:
  • 输入：
  • 步骤：
  • 预期输出/验收标准：

Example 2

示例2

Example 3

示例3

References

参考资料

  • references/index.md
    : navigation
  • references/...
    : long-form docs split by topic
  • references/index.md
    ：导航
  • references/...
    ：按主题拆分的长格式文档

Maintenance

维护

  • Sources: docs/repos/specs (do not invent)
  • Last updated: YYYY-MM-DD
  • Known limits: what is explicitly out of scope
undefined
  • 来源：文档/代码库/规范（不得编造）
  • 最后更新：YYYY-MM-DD
  • 已知限制：明确超出范围的内容
undefined

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.
  1. 快速参考用于简短、可直接使用的模式
    • 尽可能保持模式数量≤20个
    • 任何需要段落解释的内容都应移至 
      references/
  2. 激活条件必须可判定
    • 前置元数据 
      description
      应说明“功能+适用场景”，并包含具体关键词
    • “何时使用”必须列出具体任务/输入/目标，而非模糊的帮助文本
    • “不适用场景/边界”是确保可靠性的必填项
  3. 不得虚构外部细节
    • 如果素材无法证明，需说明并添加验证路径

Workflow (Material -> Skill)

工作流程（素材 -> 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
不得跳过步骤：
  1. 范围定义：写出必须/应该/绝不做的内容（三句话即可）
  2. 提取模式：挑选10-20个高频模式（命令/代码片段/流程）
  3. 添加示例：≥3个端到端示例（输入->步骤->验收标准）
  4. 定义边界：明确超出范围的内容+必要输入
  5. 拆分参考资料：将长文本移至 
    references/
    并编写 
    references/index.md
  6. 质量管控：运行检查清单和验证器

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
undefined
最低检查标准（完整版本见 
references/quality-checklist.md
）：
  1. name
    匹配正则 
    ^[a-z][a-z0-9-]*$
    且与目录名一致
  2. description
    说明“功能+适用场景”并包含具体触发关键词
  3. 包含“何时使用此技能”且触发条件可判定
  4. 包含“不适用场景/边界”以减少触发失效
  5. 快速参考的模式数量≤20个，且每个模式均可直接使用
  6. 包含≥3个可复现的示例
  7. 长内容存放在 
    references/
    中，且 
    references/index.md
    可导航
  8. 不确定的声明包含验证路径（不得虚构）
  9. 内容读起来像操作手册，而非文档堆砌
本地验证：
bash
undefined

From repo root (basic validation)

从仓库根目录（基础验证）

./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name>
./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
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name> --strict

From skills/claude-skills/ (basic validation)

从 skills/claude-skills/ 目录（基础验证）

./scripts/validate-skill.sh ../<skill-name>
./scripts/validate-skill.sh ../<skill-name>

From skills/claude-skills/ (strict validation)

从 skills/claude-skills/ 目录（严格验证）

./scripts/validate-skill.sh ../<skill-name> --strict
undefined
./scripts/validate-skill.sh ../<skill-name> --strict
undefined

Tools & Templates

工具与模板

Generate a new Skill skeleton:
bash
undefined
生成新Skill骨架：
bash
undefined

From repo root (generate into ./skills/)

从仓库根目录（生成到 ./skills/）

./skills/claude-skills/scripts/create-skill.sh my-skill --full --output skills
./skills/claude-skills/scripts/create-skill.sh my-skill --full --output skills

From skills/claude-skills/ (generate into ../ i.e. ./skills/)

从 skills/claude-skills/ 目录（生成到 ../ 即 ./skills/）

./scripts/create-skill.sh my-skill --full --output ..
./scripts/create-skill.sh my-skill --full --output ..

Minimal skeleton

最简骨架

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

Templates:
- `assets/template-minimal.md`
- `assets/template-complete.md`
./skills/claude-skills/scripts/create-skill.sh my-skill --minimal --output skills

模板：
- `assets/template-minimal.md`
- `assets/template-complete.md`

Examples

示例

Example 1: Create a Skill from Docs

示例1：从文档创建Skill

  • Input: an official doc/spec + 2-3 real code samples + common failure modes
  • Steps:
    1. Run 
      create-skill.sh
      to scaffold 
      skills/<skill-name>/
    2. Write frontmatter 
      description
      as "what + when"
    3. Extract 10-20 high-frequency patterns into Quick Reference
    4. Add >= 3 end-to-end examples with acceptance criteria
    5. Put long content into 
      references/
      and wire 
      references/index.md
    6. Run 
      validate-skill.sh --strict
      and iterate
  • 输入：官方文档/规范 + 2-3个真实代码样本 + 常见失败模式
  • 步骤：
    1. 运行 
      create-skill.sh
      搭建 
      skills/<skill-name>/
      目录结构
    2. 编写前置元数据 
      description
      ，说明“功能+适用场景”
    3. 提取10-20个高频模式到快速参考
    4. 添加≥3个端到端示例及验收标准
    5. 将长内容移至 
      references/
      并关联 
      references/index.md
    6. 运行 
      validate-skill.sh --strict
      并迭代优化

Example 2: Refactor a "Doc Dump" Skill

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

  • Input: an existing 
    SKILL.md
    with long pasted documentation
  • Steps:
    1. Identify which parts are patterns vs. long-form explanation
    2. Move long-form text into 
      references/
      (split by topic)
    3. Rewrite Quick Reference as short copy/paste patterns
    4. Add or fix Examples until they are reproducible
    5. Add "Not For / Boundaries" to reduce misfires
  • 输入：现有 
    SKILL.md
    ，包含大量粘贴的文档内容
  • 步骤：
    1. 区分哪些是模式，哪些是长格式解释
    2. 将长格式文本移至 
      references/
      （按主题拆分）
    3. 将快速参考重写为简短的可复制粘贴模式
    4. 添加或修复示例，确保其可复现
    5. 添加“不适用场景/边界”以减少触发失效

Example 3: Validate and Gate a Skill

示例3：验证并管控Skill质量

  • Input: 
    skills/<skill-name>/
  • Steps:
    1. Run 
      validate-skill.sh
      (non-strict) to get warnings
    2. Fix frontmatter/name mismatches and missing sections
    3. Run 
      validate-skill.sh --strict
      to enforce the spec
    4. Run the scoring rubric in 
      references/quality-checklist.md
      before shipping
  • 输入：
    skills/<skill-name>/
    目录
  • 步骤：
    1. 运行 
      validate-skill.sh
      （非严格模式）获取警告
    2. 修复前置元数据/名称不匹配及缺失的章节
    3. 运行 
      validate-skill.sh --strict
      以强制执行规范
    4. 交付前运行 
      references/quality-checklist.md
      中的评分标准

References

参考资料

Local docs:
  • references/index.md
  • references/skill-spec.md
  • references/quality-checklist.md
  • references/anti-patterns.md
  • references/README.md
    (upstream official reference)
External (official):
本地文档：
  • references/index.md
  • references/skill-spec.md
  • references/quality-checklist.md
  • references/anti-patterns.md
  • references/README.md
    （上游官方参考）
外部（官方）：

Maintenance

维护

  • Sources: local spec files in 
    skills/claude-skills/references/
    + upstream official docs in 
    references/README.md
  • Last updated: 2025-12-14
  • Known limits: 
    validate-skill.sh
    is heuristic; strict mode assumes the recommended section headings
  • 来源：
    skills/claude-skills/references/
    中的本地规范文件 + 
    references/README.md
    中的上游官方文档
  • 最后更新：2025-12-14
  • 已知限制：
    validate-skill.sh
    基于启发式规则；严格模式假设使用推荐的章节标题