Back to Details

skill-coach

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Coach: Creating Expert-Level Agent Skills

Skill Coach：创建专家级Agent Skills

Encode real domain expertise, not just surface-level instructions. Focus on shibboleths - the deep knowledge that separates novices from experts.
融入真正的领域专业知识，而非仅停留在表面指令层面。重点关注核心鉴别知识——即区分新手与专家的深层知识。

When to Use This Skill

何时使用此Skill

Use for:
  • Creating new Agent Skills from scratch
  • Reviewing/auditing existing skills
  • Improving skill activation rates
  • Adding domain expertise to skills
  • Debugging why skills don't activate
NOT for:
  • General Claude Code features (slash commands, MCPs)
  • Non-skill coding advice
  • Debugging runtime errors (use domain skills)
适用场景：
  • 从零开始创建新的Agent Skills
  • 审核/评估现有技能
  • 提升技能触发率
  • 为技能添加领域专业知识
  • 排查技能无法触发的原因
不适用场景：
  • 通用Claude Code功能（斜杠命令、MCP）
  • 非Skill类编码建议
  • 调试运行时错误（使用领域专属技能）

Quick Wins

快速优化技巧

Immediate improvements for existing skills:
  1. Add NOT clause to description → Prevents false activation
  2. Add 1-2 anti-patterns → Prevents common mistakes
  3. Check line count (run validator) → Should be fewer than 500 lines
  4. Remove dead files → Delete unreferenced scripts/references
  5. Test activation → Questions that should/shouldn't trigger it
现有技能的即时改进方案：
  1. 添加排除条款到描述中 → 防止误触发
  2. 添加1-2种反模式 → 避免常见错误
  3. 检查行数（运行验证工具）→ 应少于500行
  4. 删除无用文件 → 删除未引用的脚本/资源
  5. 测试触发效果 → 测试应触发和不应触发的问题

What Makes a Great Skill

优秀Skill的特质

Great skills are progressive disclosure machines that:
  1. Activate precisely - Specific keywords + NOT clause
  2. Encode shibboleths - Expert knowledge that separates novice from expert
  3. Surface anti-patterns - "If you see X, that's wrong because Y, use Z"
  4. Capture temporal knowledge - "Pre-2024: X. 2024+: Y"
  5. Know their limits - "Use for A, B, C. NOT for D, E, F"
  6. Provide decision trees - Not templates, but "If X then A, if Y then B"
  7. Stay under 500 lines - Core in SKILL.md, deep dives in /references
优秀的Skill是渐进式披露载体，具备以下特质：
  1. 精准触发 - 特定关键词 + 排除条款
  2. 融入核心鉴别知识 - 区分新手与专家的专业知识
  3. 明确反模式 - "如果出现X情况，那是错误的，原因是Y，应使用Z方案"
  4. 涵盖时效性知识 - "2024年前：X方案；2024年及以后：Y方案"
  5. 清晰边界 - "适用于A、B、C场景，不适用于D、E、F场景"
  6. 提供决策树 - 而非模板，比如"如果X则执行A，如果Y则执行B"
  7. 控制在500行以内 - 核心内容放在SKILL.md，深度内容放在/references目录

Core Principles

核心原则

Progressive Disclosure

渐进式披露

  • Phase 1 (~100 tokens): Metadata - "Should I activate?"
  • Phase 2 (<5k tokens): SKILL.md - "How do I do this?"
  • Phase 3 (as needed): References - "Show me the details"
Critical: Keep SKILL.md under 500 lines. Split details into 
/references
.
  • 阶段1（约100 tokens）：元数据 - "是否应该触发此Skill？"
  • 阶段2（<5k tokens）：SKILL.md - "如何执行操作？"
  • 阶段3（按需）：参考资料 - "查看详细内容"
关键要求：SKILL.md文件需控制在500行以内。详细内容拆分至/references目录。

Description Formula

描述公式

[What] [Use for] [Keywords] NOT for [Exclusions]
❌ Bad: "Helps with images"
⚠️ Better: "Image processing with CLIP"
✅ Good: "CLIP semantic search. Use for image-text matching.
   Activate on 'CLIP', 'embeddings'. NOT for counting, spatial reasoning."
[功能] [适用场景] [触发关键词] NOT for [排除场景]
❌ 错误示例："帮助处理图片"
⚠️ 较好示例："使用CLIP进行图像处理"
✅ 优秀示例："CLIP语义搜索。适用于图文匹配场景。
   触发关键词：'CLIP'、'embeddings'。不适用于计数、空间推理场景。"

SKILL.md Template

SKILL.md模板

markdown
---
name: your-skill-name
description: [What] [When] [Triggers]. NOT for [Exclusions].
allowed-tools: Read,Write  # Minimal only
---
markdown
---
name: your-skill-name
description: [功能] [适用场景] [触发关键词]。NOT for [排除场景]。
allowed-tools: Read,Write  # 仅保留必要权限
---

Skill Name

Skill名称

[One sentence purpose]
[一句话描述用途]

When to Use

适用场景

✅ Use for: [A, B, C] ❌ NOT for: [D, E, F]
✅ 适用于：[A、B、C] ❌ 不适用于：[D、E、F]

Core Instructions

核心指令

[Step-by-step, decision trees, not templates]
[分步说明、决策树，而非模板]

Common Anti-Patterns

常见反模式

[Pattern]

[模式名称]

Symptom: [Recognition] Problem: [Why wrong] Solution: [Better approach]
undefined
症状：[识别特征] 问题：[错误原因] 解决方案：[优化方案]
undefined

Frontmatter Rules (CRITICAL)

前置元数据规则（关键要求）

Only these frontmatter keys are allowed by Claude's skill marketplace:
KeyRequiredPurpose
name
✅Lowercase-hyphenated identifier
description
✅Activation keywords + NOT clause
allowed-tools
⚠️Comma-separated tool names
license
❌e.g., "MIT"
metadata
❌Custom key-value pairs
Invalid keys that will FAIL upload:
yaml
undefined
Claude技能市场仅允许使用以下前置元数据键：
键名是否必填用途
name
✅小写连字符格式的标识符
description
✅触发关键词 + 排除条款
allowed-tools
⚠️逗号分隔的工具名称
license
❌例如："MIT"
metadata
❌自定义键值对
会导致上传失败的无效键：
yaml
undefined

❌ WRONG - These will break skill upload

❌ 错误示例 - 这些会导致Skill上传失败

integrates_with:
  • orchestrator triggers:
  • "activate on this" tools: Read,Write outputs: formatted text coordinates_with: other-skill python_dependencies:
  • numpy

**Move custom info to the body:**
```markdown
integrates_with:
  • orchestrator triggers:
  • "activate on this" tools: Read,Write outputs: formatted text coordinates_with: other-skill python_dependencies:
  • numpy

**将自定义信息移至正文：**
```markdown

Integrations

集成说明

Works with: orchestrator, team-builder
兼容工具：orchestrator、team-builder

Activation Triggers

触发条件

Responds to: "create skill", "review skill", "skill quality"

**Validation command:**
```bash
响应关键词："create skill"、"review skill"、"skill quality"

**验证命令：**
```bash

Find invalid frontmatter keys

查找无效的前置元数据键

for skill in .claude/skills/*/SKILL.md; do sed -n '/^---$/,/^---$/p' "$skill" | grep -E "^[a-zA-Z_-]+:" | cut -d: -f1 |
grep -vE "^(name|description|license|allowed-tools|metadata)$" &&
echo " ^ in $(basename $(dirname $skill))" done
undefined
for skill in .claude/skills/*/SKILL.md; do sed -n '/^---$/,/^---$/p' "$skill" | grep -E "^[a-zA-Z_-]+:" | cut -d: -f1 |
grep -vE "^(name|description|license|allowed-tools|metadata)$" &&
echo " ^ in $(basename $(dirname $skill))" done
undefined

Skill Structure

Skill目录结构

Mandatory:
your-skill/
└── SKILL.md           # Core instructions (max 500 lines)
Strongly Recommended (self-contained skills):
├── scripts/           # Working code - NOT templates
├── mcp-server/        # Custom MCP if external APIs needed
├── agents/            # Subagent definitions if orchestration needed
├── references/        # Deep dives on domain knowledge
└── CHANGELOG.md       # Version history
必填结构：
your-skill/
└── SKILL.md           # 核心指令（最多500行）
强烈推荐结构（自包含Skill）：
├── scripts/           # 可运行代码 - 非模板
├── mcp-server/        # 如需调用外部API，自定义MCP服务
├── agents/            # 如需编排流程，定义子Agent
├── references/        # 领域知识深度解析
└── CHANGELOG.md       # 版本历史

Self-Contained Skills (RECOMMENDED)

自包含Skill（推荐）

Skills with working tools are immediately useful. See 
references/self-contained-tools.md
for full patterns.
Quick decision: External APIs? → MCP. Multi-step workflow? → Subagents. Repeatable operations? → Scripts.
具备可运行工具的Skill可立即投入使用。 查看
references/self-contained-tools.md
获取完整模式。
快速决策指南：需要调用外部API？→ 使用MCP。多步骤工作流？→ 使用子Agent。重复操作？→ 使用脚本。

Decision Trees

决策树

When to create a NEW skill?
  • ✅ Domain expertise not in existing skills
  • ✅ Pattern repeats across 3+ projects
  • ✅ Anti-patterns you want to prevent
  • ❌ One-time task → Just do it directly
  • ❌ Existing skill could be extended → Improve that one
Skill vs Subagent vs MCP?
  • Skill: Domain expertise, decision trees (no runtime state)
  • Subagent: Multi-step workflows needing tool orchestration
  • MCP: External APIs, auth, stateful connections
何时创建新Skill？
  • ✅ 现有Skill未涵盖的领域专业知识
  • ✅ 模式在3个以上项目中重复出现
  • ✅ 存在需要预防的反模式
  • ❌ 一次性任务 → 直接执行即可
  • ❌ 现有Skill可扩展 → 优化现有Skill
Skill vs 子Agent vs MCP？
  • Skill：领域专业知识、决策树（无运行时状态）
  • 子Agent：需要工具编排的多步骤工作流
  • MCP：外部API调用、认证、有状态连接

Skill Creation Process (6 Steps)

Skill创建流程（6步）

Follow these steps in order when creating a new skill:
创建新Skill时，请按以下顺序执行：

Step 1: Understand with Concrete Examples

步骤1：通过具体示例明确需求

Skip only if usage patterns are already clear. Ask:
  • "What functionality should this skill support?"
  • "Can you give examples of how it would be used?"
  • "What would a user say that should trigger this skill?"
仅当使用模式已清晰时可跳过此步骤。思考：
  • "此Skill应支持哪些功能？"
  • "能否举例说明如何使用它？"
  • "用户说什么内容时应触发此Skill？"

Step 2: Plan Reusable Contents

步骤2：规划可复用内容

For each example, analyze:
  1. How to execute from scratch
  2. What scripts, references, assets would help with repeated execution
Example analyses:
  • pdf-editor
    for "rotate this PDF" → Needs 
    scripts/rotate_pdf.py
  • frontend-webapp-builder
    → Needs 
    assets/hello-world/
    template
  • big-query
    skill → Needs 
    references/schema.md
    for table schemas
针对每个示例，分析：
  1. 如何从零开始执行
  2. 哪些脚本、参考资料、资源可帮助重复执行
示例分析：
  • 用于"旋转此PDF"的
    pdf-editor
    → 需要
    scripts/rotate_pdf.py
    脚本
  • frontend-webapp-builder
    → 需要
    assets/hello-world/
    模板
  • big-query
    Skill → 需要
    references/schema.md
    表结构文档

Step 3: Initialize the Skill

步骤3：初始化Skill

Create the skill directory structure:
your-skill/
├── SKILL.md           # Core instructions (max 500 lines)
├── scripts/           # Working code - NOT templates
├── references/        # Deep dives on domain knowledge
└── assets/            # Files used in output (templates, icons)
创建Skill目录结构：
your-skill/
├── SKILL.md           # 核心指令（最多500行）
├── scripts/           # 可运行代码 - 非模板
├── references/        # 领域知识深度解析
└── assets/            # 输出所需文件（模板、图标等）

Step 4: Write SKILL.md

步骤4：编写SKILL.md

  • Write in imperative/infinitive form ("To accomplish X, do Y")
  • Answer: Purpose? When to use? How to use bundled resources?
  • Reference all scripts/references so Claude knows they exist
  • 使用祈使语气/不定式形式（"要完成X，需执行Y"）
  • 明确回答：用途？适用场景？如何使用捆绑资源？
  • 引用所有脚本/参考资料，确保Claude知晓其存在

Step 5: Validate and Package

步骤5：验证与打包

bash
undefined
bash
undefined

Validate skill structure and content

验证Skill结构与内容

python scripts/validate_skill.py <path>
python scripts/validate_skill.py <path>

Check for self-contained tool completeness

检查自包含工具完整性

python scripts/check_self_contained.py <path>
undefined
python scripts/check_self_contained.py <path>
undefined

Step 6: Iterate

步骤6：迭代优化

After real-world use:
  1. Notice struggles or inefficiencies
  2. Identify how SKILL.md or bundled resources should be updated
  3. Implement changes and test again
实际使用后：
  1. 记录遇到的问题或低效点
  2. 分析应如何更新SKILL.md或捆绑资源
  3. 实施变更并再次测试

Common Workflows

常见工作流

Create Skill from Expertise:
  1. Define scope: What expertise? What keywords? What NOT to handle?
  2. Write description with keywords and NOT clause
  3. Add anti-patterns you've observed
  4. Test activation thoroughly
Debug Activation Issues (flowchart):
Skill not activating when expected?
├── Check description has specific keywords
│   ├── NO → Add "Activate on: keyword1, keyword2"
│   └── YES → Check if query contains those keywords
│       ├── NO → Add missing keyword variations
│       └── YES → Check for conflicting NOT clause
│           ├── YES → Narrow exclusion scope
│           └── NO → Check file structure
│               ├── SKILL.md missing → Create it
│               └── Wrong location → Move to .claude/skills/

Skill activating when it shouldn't?
├── Missing NOT clause?
│   ├── YES → Add "NOT for: exclusion1, exclusion2"
│   └── NO → NOT clause too narrow
│       └── Expand exclusions based on false positive queries
Run 
python scripts/test_activation.py <path>
to validate
Recursive Self-Improvement (use this skill to improve skills):
  1. Run 
    python scripts/validate_skill.py <path>
    → Get validation report
  2. Run 
    python scripts/check_self_contained.py <path>
    → Check tool completeness
  3. Address ERRORS first, then WARNINGS, then SUGGESTIONS
  4. Re-run validation until clean
  5. Update CHANGELOG.md with improvements made
基于专业知识创建Skill：
  1. 定义范围：涵盖哪些专业知识？触发关键词？不处理哪些场景？
  2. 编写包含关键词和排除条款的描述
  3. 添加已观察到的反模式
  4. 全面测试触发效果
排查触发问题（流程图）：
Skill未按预期触发？
├── 检查描述是否包含特定关键词
│   ├── 否 → 添加"触发关键词：keyword1, keyword2"
│   └── 是 → 检查查询是否包含这些关键词
│       ├── 否 → 添加缺失的关键词变体
│       └── 是 → 检查是否存在冲突的排除条款
│           ├── 是 → 缩小排除范围
│           └── 否 → 检查文件结构
│               ├── 缺少SKILL.md → 创建该文件
│               └── 位置错误 → 移至.claude/skills/目录

Skill被误触发？
├── 是否缺少排除条款？
│   ├── 是 → 添加"不适用于：exclusion1, exclusion2"
│   └── 否 → 排除条款范围过窄
│       └── 根据误触发查询扩展排除场景
运行
python scripts/test_activation.py <path>
进行验证
递归自我优化（使用此Skill优化其他Skill）：
  1. 运行
    python scripts/validate_skill.py <path>
    → 获取验证报告
  2. 运行
    python scripts/check_self_contained.py <path>
    → 检查工具完整性
  3. 优先解决错误，其次是警告，最后是建议
  4. 重新运行验证直到无问题
  5. 更新CHANGELOG.md记录改进内容

Tool Permissions

工具权限

Guidelines:
  • Read-only skill: 
    Read,Grep,Glob
  • File modifier: 
    Read,Write,Edit
  • Build integration: 
    Read,Write,Bash(npm:*,git:*)
  • ⚠️ Never: Unrestricted 
    Bash
    for untrusted skills
权限指南：
  • 只读Skill：
    Read,Grep,Glob
  • 文件修改Skill：
    Read,Write,Edit
  • 构建集成Skill：
    Read,Write,Bash(npm:*,git:*)
  • ⚠️ 禁止：为不可信Skill授予无限制的
    Bash
    权限

Success Metrics

成功指标

MetricTarget
Correct activation>90%
False positive rate<5%
Token usage<5k typical
指标目标值
正确触发率>90%
误触发率<5%
Token使用量通常<5k

Reference Files

参考文件

FileContents
references/antipatterns.md
Domain shibboleths and anti-pattern catalog with case studies
references/shibboleths.md
Expert vs novice knowledge patterns
references/validation-checklist.md
Complete review and testing guide
references/self-contained-tools.md
Scripts, MCP servers, and subagent implementation patterns
references/scoring-rubric.md
Quantitative skill evaluation (0-10 scoring)
references/skill-composition.md
Cross-skill dependencies and composition patterns
references/skill-lifecycle.md
Maintenance, versioning, and deprecation guidance
references/mcp_vs_scripts.md
Architectural decision guide: Skills vs Agents vs MCPs vs Scripts
This skill guides: Skill creation | Skill auditing | Anti-pattern detection | Progressive disclosure | Domain expertise encoding
文件内容
references/antipatterns.md
领域核心鉴别知识与反模式案例集
references/shibboleths.md
专家与新手的知识差异模式
references/validation-checklist.md
完整的审核与测试指南
references/self-contained-tools.md
脚本、MCP服务与子Agent实现模式
references/scoring-rubric.md
量化Skill评估标准（0-10分）
references/skill-composition.md
跨Skill依赖与组合模式
references/skill-lifecycle.md
维护、版本控制与废弃指南
references/mcp_vs_scripts.md
架构决策指南：Skills vs Agents vs MCPs vs Scripts
此Skill可指导： Skill创建 | Skill审核 | 反模式检测 | 渐进式披露 | 领域专业知识编码