expertise-distiller

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Expertise Distiller: Principle-Driven Skill Design

专业知识提炼器:原则驱动的Skill设计

This skill guides you through creating skills that transfer expertise, not just list instructions.
本Skill会指导你创建能够传递专业知识的Skill,而不只是罗列操作指令。

The 4 Core Truths

四大核心真理

Every skill you create must embody these principles:
TruthWhat It MeansIn Practice
Expertise Transfer, Not InstructionsMake Claude think like an expert, not follow stepsTeach mental models and decision frameworks, not checklists
Flow, Not FrictionProduce output, not intermediate documentsGo straight to deliverables - no "now write a plan" steps
Voice Matches DomainSound like a practitioner, not documentationUse domain language naturally, avoid meta-commentary
Focused Beats ComprehensiveConstrain ruthlesslyEvery section must justify its token cost
你创建的每一个Skill都必须遵循这些原则:
核心真理含义实践要求
专业知识传递,而非指令罗列让Claude像专家一样思考,而不是按步骤执行教授思维模型和决策框架,而非检查清单
流程顺滑,无冗余摩擦直接产出结果,而非生成中间文档直接输出交付物,不要有「现在写一个方案」这类步骤
风格匹配领域特性听起来像行业从业者输出,而非官方文档自然使用领域术语,避免元注释
聚焦优先,全面次之ruthlessly 控制内容范围每一部分内容都要证明其Token消耗是有价值的

When to Use This Skill

何时使用本Skill

Use this skill when:
  • Creating a new skill from scratch
  • A skill isn't performing well and needs rethinking
  • You want to understand why certain patterns work
  • You need to make tough trade-offs about what to include
Don't use this for:
  • Quick iterations on working skills (use the standard skill-creator)
  • Just packaging an existing skill (use packaging scripts directly)
符合以下场景时可使用本Skill:
  • 从零创建一个新Skill
  • 现有Skill表现不佳需要重新设计
  • 你想要理解特定模式生效的底层原因
  • 你需要对Skill包含的内容做艰难取舍
不要在以下场景使用:
  • 对可用的Skill做快速迭代(使用标准的skill-creator即可)
  • 仅需打包现有Skill(直接使用打包脚本即可)

The 10-Step Process

10步流程

UNDERSTAND the problem
EXPLORE Claude's failures  
RESEARCH domain expertise
SYNTHESIZE principles
DRAFT the skill
SELF-CRITIQUE rigorously
ITERATE on feedback
TEST on real scenarios
FINALIZE structure
PACKAGE for distribution
UNDERSTAND the problem
EXPLORE Claude's failures  
RESEARCH domain expertise
SYNTHESIZE principles
DRAFT the skill
SELF-CRITIQUE rigorously
ITERATE on feedback
TEST on real scenarios
FINALIZE structure
PACKAGE for distribution

1. UNDERSTAND → What skill? What problem?

1. 理解(UNDERSTAND)→ 做什么Skill?解决什么问题?

Start by crystallizing the core need:
  • What specific capability gap exists? (Not "documentation" but "Claude rewrites the same 50-line parsing script every time")
  • What does success look like? (Concrete examples of before/after)
  • Who benefits and how? (Time saved? Quality improved? Consistency achieved?)
Good examples:
  • "Engineers spend 20 minutes each time formatting API responses to match our schema"
  • "Claude generates valid SQL but doesn't know our table relationships"
  • "We need Claude to follow our 47-point brand guidelines without a wall of text"
Bad examples:
  • "Make Claude better at X" (too vague)
  • "Help with documents" (too broad)
Output: A crisp problem statement you could explain in 30 seconds.
首先明确核心需求:
  • 存在什么具体的能力缺口?(不是「文档相关」,而是「Claude每次都会重复写相同的50行解析脚本」)
  • 成功的标准是什么?(给出优化前后的具体示例)
  • 谁会受益,如何受益?(节省时间?提升质量?实现一致性?)
正面示例:
  • "工程师每次格式化API响应匹配我们的Schema都要花20分钟"
  • "Claude可以生成可用的SQL,但不了解我们的表关联关系"
  • "我们需要Claude遵循我们的47条品牌规范,不用每次都贴大段文本"
反面示例:
  • "让Claude更擅长做X"(太模糊)
  • "处理文档相关需求"(太宽泛)
**产出:**一个30秒就能讲清楚的清晰问题说明。

2. EXPLORE → See where Claude fails without guidance

2. 探索(EXPLORE)→ 查看Claude没有指导时的失败场景

Critical step - don't skip this. You need to observe the failure mode, not imagine it.
Try the task without the skill:
  1. Give Claude a representative request
  2. Note where it struggles, hesitates, or produces suboptimal output
  3. Try 3-5 variations to see if it's consistent
Document:
  • What did Claude do wrong?
  • What knowledge was it missing?
  • What did it waste time on?
  • When did it ask for clarification vs. guess?
Example observations:
  • "Claude generated working code but used pandas when our stack is polars"
  • "Claude wrote a 200-line form instead of using our 10-line template"
  • "Claude asked what format we wanted - it should know we always use ISO 8601"
Why this matters: You're designing for actual failure modes, not theoretical ones. This prevents over-specifying (wasting tokens) or under-specifying (skill doesn't help).
**关键步骤,不要跳过。**你需要观察实际的失败模式,而不是凭空想象。
不使用目标Skill尝试完成任务:
  1. 给Claude一个典型的需求
  2. 记录它吃力、犹豫或者输出不达标的地方
  3. 尝试3-5个变体需求,确认问题是否稳定复现
记录内容:
  • Claude哪里做错了?
  • 它缺少什么知识?
  • 它在什么内容上浪费了时间?
  • 它什么时候会要求澄清,什么时候会自行猜测?
观察示例:
  • "Claude生成了可用的代码,但我们的技术栈用的是polars,它用了pandas"
  • "Claude写了200行的表单代码,没有用我们现成的10行模板"
  • "Claude问我们要什么格式,它应该知道我们统一用ISO 8601"
**重要性:**你是针对实际的失败模式做设计,而不是理论上的。这可以避免过度定义(浪费Token)或者定义不足(Skill没有实际作用)。

3. RESEARCH → Go deep on the domain

3. 研究(RESEARCH)→ 深入了解领域知识

Now that you know what fails, understand why success looks like and what experts know.
For technical domains:
  • What mental models do experts use?
  • What are the key decision points?
  • What patterns repeat across scenarios?
  • What's stable vs. what varies?
For workflow domains:
  • What's the expert's internal checklist?
  • What do they check for quality?
  • What shortcuts do they know?
  • What mistakes do novices make?
Research sources:
  • Interview domain experts
  • Review high-quality examples
  • Read practitioner documentation (not beginner tutorials)
  • Analyze your own expert behavior
Output: A list of insights that would make Claude competent, not just capable.
现在你已经知道哪里会出问题,接下来要理解成功的标准是什么,以及专家掌握的知识有哪些。
针对技术领域:
  • 专家会用什么思维模型?
  • 关键决策点有哪些?
  • 不同场景下重复出现的模式是什么?
  • 什么内容是固定的,什么是可变的?
针对工作流领域:
  • 专家内部的检查清单是什么?
  • 他们会从哪些维度校验质量?
  • 他们知道哪些捷径?
  • 新手常犯的错误有哪些?
研究来源:
  • 访谈领域专家
  • 查阅高质量的参考示例
  • 阅读从业者导向的文档(不是新手教程)
  • 分析你自己作为专家的行为习惯
**产出:**一系列能让Claude达到胜任水平的洞察,而不只是具备基础能力。

4. SYNTHESIZE → Extract principles from research

4. 综合(SYNTHESIZE)→ 从研究中提炼原则

Transform observations into teachable principles.
Pattern recognition:
  • What do all good examples have in common?
  • What varies based on context?
  • What rules have exceptions? (Document both)
  • What can be expressed as "if X then Y"?
Compression:
  • Can 5 bullet points become 1 principle?
  • Can 3 examples show a pattern?
  • Can a decision tree replace prose?
Example synthesis:
Raw research:
- Example 1 uses indentation for hierarchy
- Example 2 uses bullet points for parallel items
- Example 3 uses numbered lists for sequences
- Example 4 combines all three appropriately

Synthesized principle:
"Match structure to meaning: indent for hierarchy, bullets for parallelism, numbers for sequence."
Output: Distilled principles that transfer expertise, not just information.
把观察到的内容转化为可教授的原则。
模式识别:
  • 所有好的示例有什么共同点?
  • 什么内容会随上下文变化?
  • 哪些规则存在例外?(两者都要记录)
  • 什么内容可以表达为「如果X则Y」的形式?
内容压缩:
  • 5个要点能不能合并成1条原则?
  • 3个示例能不能说明一个模式?
  • 能不能用决策树代替大段文字?
综合示例:
原始研究内容:
- 示例1用缩进表示层级
- 示例2用 bullet 点表示并列项
- 示例3用有序列表表示步骤序列
- 示例4恰当地组合了以上三种形式

提炼后的原则:
"结构匹配语义:层级用缩进,并列用 bullet 点,序列用有序列表。"
**产出:**经过提炼的原则,用于传递专业知识,而不只是传递信息。

5. DRAFT → Write initial skill

5. 起草(DRAFT)→ 编写初始Skill

Now you can draft. Structure using progressive disclosure:
skill-name/
├── SKILL.md          # Core workflow + principles (<500 lines)
│   ├── YAML frontmatter (name, description)
│   └── Essential instructions
├── references/       # Deep knowledge (loaded as needed)
│   ├── patterns.md
│   └── examples.md
├── scripts/          # Executable code
│   └── helper.py
└── assets/           # Templates, not documentation
    └── template.json
Frontmatter:
yaml
---
name: skill-name
description: >
  What the skill does + when to trigger it. Be specific about use cases.
  Good: "Process medical transcripts following HIPAA guidelines, including
  de-identification and structured output formatting."
  Bad: "Help with medical documents."
---
SKILL.md structure:
markdown
undefined
现在可以开始起草了,使用渐进式披露的结构:
skill-name/
├── SKILL.md          # 核心工作流 + 原则(<500行)
│   ├── YAML 头部(名称、描述)
│   └── 核心指令
├── references/       # 深度知识(按需加载)
│   ├── patterns.md
│   └── examples.md
├── scripts/          # 可执行代码
│   └── helper.py
└── assets/           # 模板,非文档
    └── template.json
YAML头部:
yaml
---
name: skill-name
description: >
  Skill的作用 + 触发时机。使用场景要具体。
  正面示例:"遵循HIPAA规范处理医疗转录内容,包括去标识化和结构化输出格式化。"
  反面示例:"处理医疗文档相关需求。"
---
SKILL.md 结构:
markdown
undefined

Skill Name

Skill名称

[One paragraph: what problem this solves]
[一段说明:本Skill解决什么问题]

Core Approach

核心方法

[The mental model - how an expert thinks about this domain]
[思维模型 - 专家对该领域的思考方式]

When [Most Common Scenario]

当[最常见场景]时

[Direct instructions using imperative form] [Include only essential decision points] [Reference detailed guides in references/ as needed]
[使用祈使句编写直接指令] [仅包含核心决策点] [需要时引用references/下的详细指南]

When [Second Most Common Scenario]

当[第二常见场景]时

[...]
[...]

Quality Checks

质量检查

[What good output looks like - help Claude self-evaluate]

**Key drafting principles:**

1. **Imperative mood**: "Extract text" not "You should extract text"
2. **Example over explanation**: Show one good example > describe in prose
3. **Decision points explicit**: "If X then Y, otherwise Z"
4. **Offload detail**: "See references/advanced.md" not "here's 500 words"
5. **Quality criteria**: Help Claude know when it's done
[合格输出的标准 - 帮助Claude自我评估]

**核心起草原则:**

1. **祈使语气**:用「提取文本」而不是「你应该提取文本」
2. **示例优于解释**:一个好的示例 > 大段文字描述
3. **明确决策点**:「如果X则Y,否则Z」
4. **细节下沉**:用「参考references/advanced.md」而不是直接放500字说明
5. **明确质量标准**:帮助Claude知道什么时候任务完成

6. SELF-CRITIQUE → Review against quality criteria

6. 自我批判(SELF-CRITIQUE)→ 对照质量标准审查

Now be ruthlessly critical. For each section, ask:
Expertise Transfer Test:
  • Does this make Claude think like an expert or just act like one?
  • Would a domain expert recognize this approach?
  • Are we teaching patterns or prescribing steps?
Flow Test:
  • Can Claude go straight to output?
  • Do we force intermediate artifacts Claude doesn't need?
  • Would an expert work this way?
Voice Test:
  • Does this sound like domain documentation or AI instructions?
  • Would a practitioner say "execute step 3" or just do it?
  • Are we narrating process or enabling work?
Focus Test:
  • Can we delete this section and still succeed? (If yes, delete it)
  • Is this addressing observed failure modes? (If no, question it)
  • Could this be a one-line reference instead?
Token Efficiency Test:
  • Would this information surprise Claude? (If no, cut it)
  • Is this stable knowledge vs. variable context?
  • Should this be in SKILL.md or references/?
Progressive Disclosure Test:
  • Do we force-load information Claude might not need?
  • Can variations go in separate reference files?
  • Are scripts documented or just executable?
Red flags:
  • Phrases like "you should", "make sure to", "don't forget"
  • Apologetic language: "This might seem complex but..."
  • Meta-commentary: "The next step is to..."
  • Over-specification: Dictating every detail when heuristics suffice
  • Under-specification: Vague guidance on fragile operations
现在要进行严格的自我审查,对每一部分问自己以下问题:
专业知识传递测试:
  • 这部分内容是让Claude像专家一样思考还是只是像专家一样行动
  • 领域专家会认可这个方法吗?
  • 我们是在教授模式还是规定步骤?
流程顺滑测试:
  • Claude可以直接产出结果吗?
  • 我们有没有强制Claude生成不需要的中间产物?
  • 专家会这么工作吗?
风格测试:
  • 内容听起来像领域文档还是AI指令?
  • 从业者会说「执行步骤3」还是直接做?
  • 我们是在叙述流程还是在赋能工作?
聚焦测试:
  • 删掉这部分我们还能达到目标吗?(如果是,就删掉)
  • 这部分是针对观察到的失败模式的吗?(如果不是,考虑删掉)
  • 这部分能不能改成一行引用?
Token效率测试:
  • 这个信息对Claude来说是陌生的吗?(如果不是,删掉)
  • 这是固定知识还是可变上下文?
  • 这部分应该放在SKILL.md还是references/里?
渐进式披露测试:
  • 我们有没有强制加载Claude可能不需要的信息?
  • 变体内容能不能放到单独的参考文件里?
  • 脚本有没有文档还是只有可执行文件?
危险信号:
  • 类似「你应该」、「请确保」、「不要忘记」这类表述
  • 抱歉式表述:「这看起来可能有点复杂但是...」
  • 元注释:「下一步是...」
  • 过度定义:启发式规则足够的情况下规定了所有细节
  • 定义不足:对容易出错的操作给出的指导太模糊

7. ITERATE → Fix gaps, get feedback, improve

7. 迭代(ITERATE)→ 修复缺口,收集反馈,优化改进

Testing approaches:
  1. Yourself: Use the skill on real scenarios - note friction
  2. Others: Have someone else try it - watch where they struggle
  3. Claude: Have Claude use it - monitor for confusion or errors
Feedback loop:
Use skill → Note issue → Hypothesis on why → Update skill → Test again
Common improvements:
  • Too much guidance: Claude over-thinks → Trust Claude more, delete text
  • Too little guidance: Claude guesses wrong → Add decision framework
  • Wrong abstraction: Scenarios don't map cleanly → Reorganize around real patterns
  • Missing context: Claude lacks key info → Move knowledge from your head to references/
Iteration triggers:
  • Claude asks questions that the skill should answer
  • Output quality varies unexpectedly
  • Claude ignores parts of the skill
  • You find yourself adding ad-hoc instructions in chat
测试方法:
  1. **自己测试:**在真实场景下使用Skill - 记录摩擦点
  2. **他人测试:**让其他人试用 - 观察他们哪里遇到问题
  3. **Claude测试:**让Claude使用Skill - 监控是否出现困惑或者错误
反馈循环:
使用Skill → 记录问题 → 假设问题原因 → 更新Skill → 再次测试
常见优化方向:
  • **指导过多:**Claude过度思考 → 给Claude更多信任,删掉冗余文本
  • **指导不足:**Claude猜错 → 补充决策框架
  • **抽象错误:**场景匹配度低 → 围绕真实模式重新组织内容
  • **上下文缺失:**Claude缺少关键信息 → 把你脑子里的知识移到references/里
迭代触发条件:
  • Claude问的问题本应该由Skill回答
  • 输出质量出现意外波动
  • Claude忽略了Skill的部分内容
  • 你需要在聊天中补充临时指令

8. TEST → Use skill on a real scenario

8. 测试(TEST)→ 在真实场景下使用Skill

Final validation with a realistic task:
  1. Pick a task that's representative but not used during design
  2. Use the skill as if you're a new user
  3. Document:
    • Did it work on first try?
    • Where did Claude hesitate?
    • What did you need to clarify?
    • Was anything missing?
    • Was anything unused?
Success criteria:
  • Claude produces quality output without ad-hoc guidance
  • The skill handles expected variations naturally
  • Token usage is reasonable (<2000 tokens loaded typically)
  • Claude doesn't ask questions the skill should answer
用真实任务做最终验证:
  1. 选择一个任务,具有代表性但没有在设计过程中使用过
  2. 像新用户一样使用这个Skill
  3. 记录:
    • 第一次使用就生效了吗?
    • Claude在哪里犹豫了?
    • 你需要补充什么澄清信息?
    • 有没有缺失的内容?
    • 有没有没用上的内容?
成功标准:
  • Claude不需要额外临时指导就能输出高质量结果
  • Skill可以自然处理预期内的变体需求
  • Token消耗合理(通常加载内容<2000 Token)
  • Claude不会问本应该由Skill回答的问题

9. FINALIZE → Codify into optimal structure

9. 终稿(FINALIZE)→ 整理为最优结构

Polish for production:
SKILL.md:
  • Remove TODOs and draft artifacts
  • Verify all references exist and are linked
  • Ensure imperative mood throughout
  • Trim any remaining cruft
References:
  • Organize by use case (not by type)
  • Add grep-able patterns for large files
  • Include only what Claude might need
Scripts:
  • Test thoroughly
  • Include docstrings (Claude might read them)
  • Consider: should this be a reference instead?
Assets:
  • Only include files that are used in output
  • Remove examples/samples unless they're templates
Validation:
bash
undefined
打磨到生产可用状态:
SKILL.md:
  • 移除TODO和草稿产物
  • 验证所有引用存在且链接正确
  • 确保全程使用祈使语气
  • 删掉所有剩余冗余内容
References:
  • 按使用场景组织(不是按内容类型)
  • 大文件添加可grep的模式标记
  • 仅包含Claude可能需要的内容
Scripts:
  • 充分测试
  • 添加docstring(Claude可能会读取)
  • 考虑:这部分是不是应该改成参考文档?
Assets:
  • 仅包含输出会用到的文件
  • 除非是模板,否则删掉示例/样例文件
验证:
bash
undefined

Use the packaging script - it validates automatically

使用打包脚本 - 它会自动做验证

scripts/package_skill.py /path/to/skill-folder
undefined
scripts/package_skill.py /path/to/skill-folder
undefined

10. PACKAGE → Share the skill

10. 打包(PACKAGE)→ 分享Skill

Once validated:
bash
undefined
验证通过后:
bash
undefined

Creates skill-name.skill file

生成 skill-name.skill 文件

scripts/package_skill.py /path/to/skill-folder /output/directory

The .skill file is a zip with a .skill extension containing your complete skill structure.
scripts/package_skill.py /path/to/skill-folder /output/directory

.skill文件是后缀为.skill的zip包,包含完整的Skill结构。

Common Skill Patterns

常见Skill模式

High-Level Guide with Deep References

带深度参考的高层指南

When: Complex domain with many variations
SKILL.md:
markdown
undefined
**适用场景:**变体多的复杂领域
SKILL.md:
markdown
undefined

Core workflow

核心工作流

[Essential steps + decision points]
For detailed guidance:
  • Pattern library: See references/patterns.md
  • Full examples: See references/examples.md
  • API reference: See references/api.md

**Benefit:** SKILL.md stays focused; Claude loads depth only when needed
[核心步骤 + 决策点]
详细指南参考:
  • 模式库: 见 references/patterns.md
  • 完整示例: 见 references/examples.md
  • API参考: 见 references/api.md

**优势:**SKILL.md保持精简,Claude只在需要时加载深度内容

Script-Heavy with Minimal Instructions

脚本为主、指令极简的模式

When: Fragile operations requiring exact execution
SKILL.md:
markdown
undefined
**适用场景:**需要精确执行的易出错操作
SKILL.md:
markdown
undefined

Rotating PDFs

旋转PDF

Use scripts/rotate_pdf.py:
```bash python scripts/rotate_pdf.py input.pdf --angle 90 --output rotated.pdf ```
The script handles edge cases and validation.

**Benefit:** Deterministic, token-efficient, no "reinventing the wheel"
使用 scripts/rotate_pdf.py:
bash
python scripts/rotate_pdf.py input.pdf --angle 90 --output rotated.pdf
脚本会处理边缘 case 和校验。

**优势:**结果确定、Token效率高,不会「重复造轮子」

Template-Based with Examples

带示例的模板驱动模式

When: Output follows a strict format
SKILL.md:
markdown
undefined
**适用场景:**输出需要遵循严格格式
SKILL.md:
markdown
undefined

Report format

报告格式

ALWAYS use this structure:
必须使用以下结构:

[Title]

[标题]

Executive Summary

执行摘要

[One paragraph]
[一段内容]

Key Findings

核心发现

  • Finding 1 [with data]
  • Finding 2 [with data]
  • 发现1 [附带数据]
  • 发现2 [附带数据]

Recommendations

建议

  1. Specific action
  2. Specific action

**Benefit:** Claude produces consistent output without guessing
  1. 具体行动
  2. 具体行动

**优势:**Claude不用猜测就能输出一致的结果

Anti-Patterns to Avoid

需要避免的反模式

Anti-PatternWhy It's BadFix
Novel-length SKILL.mdWastes tokens, hard to maintainSplit into references/
Step-by-step recipesMakes Claude mechanical, not thoughtfulTeach principles
Generic adviceClaude already knows thisOnly include novel info
Assuming incompetenceOver-explains, wastes tokensTrust Claude's base knowledge
README/CHANGELOG/etcAI doesn't need meta-documentationDelete these files
Loading everything upfrontWastes contextUse progressive disclosure
Vague triggeringSkill loaded when not neededBe specific in description
反模式坏处修复方案
长篇大论的SKILL.md浪费Token,难维护拆分到references/目录
一步步的操作指南让Claude变得机械,没有思考能力教授原则
通用建议Claude本来就知道这些内容仅包含新的信息
假设Claude能力不足过度解释,浪费Token信任Claude的基础知识
README/CHANGELOG等文件AI不需要元文档删掉这些文件
提前加载所有内容浪费上下文使用渐进式披露
触发条件模糊不需要的时候也会加载Skill描述里明确触发场景

Degrees of Freedom Framework

自由度框架

Match instruction specificity to task fragility:
High Freedom (General Guidance)
  • Use when: Multiple valid approaches exist
  • Format: Principles + examples
  • Example: "Write engaging product copy"
Medium Freedom (Preferred Patterns)
  • Use when: Best practices exist but context varies
  • Format: Decision framework + examples
  • Example: "Structure SQL queries for readability"
Low Freedom (Exact Execution)
  • Use when: Operations are fragile or compliance-critical
  • Format: Scripts or strict templates
  • Example: "Fill IRS tax forms"
根据任务的脆弱程度匹配指令的具体程度:
高自由度(通用指导)
  • 适用场景:存在多种有效方案
  • 格式:原则 + 示例
  • 示例:「写有吸引力的产品文案」
中自由度(推荐模式)
  • 适用场景:存在最佳实践但上下文可变
  • 格式:决策框架 + 示例
  • 示例:「编写可读性高的SQL查询」
低自由度(精确执行)
  • 适用场景:操作脆弱或者合规要求严格
  • 格式:脚本或者严格模板
  • 示例:「填写IRS税务表格」

Working with Existing Skills

处理现有Skill

To improve a skill:
  1. Use it on real tasks - note where it fails
  2. Check: Is this a skill problem or wrong use case?
  3. Run through EXPLORE phase again
  4. Apply targeted fixes (resist full rewrites)
  5. Test that fixes don't break existing use cases
To merge skills:
Only if they share 80%+ overlap. Otherwise keep separate - Claude can use multiple skills.
To split a skill:
When SKILL.md exceeds 500 lines or covers truly distinct workflows. Split at natural boundaries, update descriptions.
优化现有Skill:
  1. 在真实任务中使用 - 记录失败点
  2. 检查:是Skill的问题还是用错了场景?
  3. 重新走一遍探索(EXPLORE)阶段
  4. 做针对性修复(不要直接全量重写)
  5. 测试修复不会破坏现有使用场景
合并Skill:
仅当重合度超过80%时才合并,否则保持独立 - Claude可以同时使用多个Skill。
拆分Skill:
当SKILL.md超过500行或者覆盖完全不同的工作流时拆分,在自然边界处拆分,更新描述。

Quick Reference: Skill Creation Checklist

快速参考:Skill创建检查清单

  • Problem clearly defined with concrete examples
  • Observed Claude's actual failure modes (not assumed)
  • Researched domain to extract expert mental models
  • Synthesized principles, not just collected facts
  • SKILL.md under 500 lines
  • Description is specific about when to trigger
  • Imperative mood throughout
  • Progressive disclosure: SKILL.md → references → scripts
  • Every section justified by observed need
  • Tested on realistic scenarios
  • No README, CHANGELOG, or meta-docs
  • Packaged and validated
  • 问题已经明确定义,有具体示例
  • 观察了Claude的实际失败模式(不是假设的)
  • 做了领域研究,提炼了专家思维模型
  • 提炼了原则,不只是收集事实
  • SKILL.md 少于500行
  • 描述里明确了触发时机
  • 全程使用祈使语气
  • 渐进式披露:SKILL.md → references → scripts
  • 每一部分都对应观察到的实际需求
  • 在真实场景下做过测试
  • 没有README、CHANGELOG或者元文档
  • 已经打包并验证通过

References

参考

For detailed patterns:
  • Workflow patterns: See the standard skill-creator's references/workflows.md
  • Output patterns: See the standard skill-creator's references/output-patterns.md
详细模式参考:
  • 工作流模式: 见标准skill-creator的 references/workflows.md
  • 输出模式: 见标准skill-creator的 references/output-patterns.md

Tools

工具

Use the standard skill-creator scripts:
  • scripts/init_skill.py
    - Initialize skill structure
  • scripts/package_skill.py
    - Validate and package
  • scripts/quick_validate.py
    - Check structure only
使用标准skill-creator脚本:
  • scripts/init_skill.py
    - 初始化Skill结构
  • scripts/package_skill.py
    - 验证并打包
  • scripts/quick_validate.py
    - 仅检查结构

Final Wisdom

最后提示

The best skill is the one that disappears. When Claude uses it, it should feel like Claude "just knows" how to do the task - not like it's following a manual.
If your skill makes Claude sound like it's reading instructions, you've created friction. If Claude sounds like a domain expert who happens to have expertise in this area, you've transferred expertise.
That's the difference.
**最好的Skill是存在感为零的Skill。**当Claude使用它的时候,感觉就像Claude「本来就知道」怎么完成这个任务,而不是在跟着手册执行。
如果你的Skill让Claude听起来像在读指令,那你就制造了摩擦。如果Claude听起来像刚好掌握了这个领域知识的专家,那你就实现了专业知识的传递。
这就是核心区别。