skill-coach

Skill Coach：创建专家级 Agent Skills

编码真实的领域专业知识，而不只是表面指令。重点关注行话暗号——区分新手与专家的深层知识。

何时使用此 Skill

适用于：

• 从头创建新的 Agent Skills
• 审查／审计现有 Skills
• 提高 Skill 激活率
• 为 Skills 添加领域专业知识
• 调试 Skill 为何没有激活

不适用于：

• Claude Code 的通用功能（斜杠命令、MCP）
• 与 Skill 无关的编程建议
• 调试运行时错误（请使用领域 Skills）

快速见效的改进

对现有 Skills 的即时改进：

1. 在描述中添加 NOT 子句 → 防止误激活
2. 添加 1–2 个反模式 → 防止常见错误
3. 检查行数（运行验证器）→ 应少于 500 行
4. 删除无用文件 → 删除未引用的脚本／参考资料
5. 测试激活情况 → 检查哪些问题应该／不应该触发它

优秀 Skill 的特点

优秀的 Skills 是渐进式披露机器，能够：

1. 精准激活——特定关键词 + NOT 子句
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

核心原则

渐进式披露

• 阶段 1（约 100 个 token）：元数据——“我应该激活吗？”
• 阶段 2（少于 5k 个 token）：SKILL.md——“我该怎么做？”
• 阶段 3（按需）：参考资料——“给我看看详细信息”

重要：SKILL.md 应少于 500 行。将详细内容拆分到 /references。

描述公式

[内容] [适用场景] [关键词] NOT for [排除项]

❌ 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."

SKILL.md 模板

---
name: your-skill-name
description: [What] [When] [Triggers]. NOT for [Exclusions].
allowed-tools: Read,Write  # Minimal only
---

# Skill Name
[One sentence purpose]

## When to Use
✅ Use for: [A, B, C]
❌ NOT for: [D, E, F]

## Core Instructions
[Step-by-step, decision trees, not templates]

## Common Anti-Patterns
### [Pattern]
**Symptom**: [Recognition]
**Problem**: [Why wrong]
**Solution**: [Better approach]

Frontmatter 规则（重要）

Claude 的 Skill Marketplace 仅允许使用以下 frontmatter 键：

键	必填	用途
name	✅	小写、以连字符分隔的标识符
description	✅	激活关键词 + NOT 子句
allowed-tools	⚠️	以逗号分隔的工具名称
license	❌	例如，“MIT”
metadata	❌	自定义键值对

会导致上传失败的无效键：

# ❌ WRONG - These will break skill upload
integrates_with:
  - orchestrator
triggers:
  - "activate on this"
tools: Read,Write
outputs: formatted text
coordinates_with: other-skill
python_dependencies:
  - numpy

将自定义信息移至正文：

## Integrations
Works with: orchestrator, team-builder

## Activation Triggers
Responds to: "create skill", "review skill", "skill quality"

验证命令：

# 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

Skill 结构

必需内容：

your-skill/
└── SKILL.md           # Core instructions (max 500 lines)

强烈推荐（自包含 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

自包含 Skills（推荐）

**具备可用工具的 Skills 能立即发挥作用。**完整模式请参阅 references/self-contained-tools.md。

快速决策：外部 API？→ MCP。多步骤工作流？→ 子 Agent。可重复操作？→ 脚本。

决策树

何时创建新 Skill？

• ✅ 现有 Skills 中没有的领域专业知识
• ✅ 同一模式在 3 个或更多项目中反复出现
• ✅ 希望预防的反模式
• ❌ 一次性任务 → 直接处理即可
• ❌ 可以扩展现有 Skill → 改进现有 Skill

Skill、子 Agent 还是 MCP？

• Skill：领域专业知识、决策树（无运行时状态）
• 子 Agent：需要工具编排的多步骤工作流
• MCP：外部 API、身份验证、有状态连接

Skill 创建流程（6 个步骤）

创建新 Skill 时，请按顺序执行以下步骤：

步骤 1：通过具体示例了解需求

只有在使用模式已经清晰时才跳过。询问：

• “此 Skill 应支持哪些功能？”
• “能否举例说明它会如何使用？”
• “用户会说什么话来触发此 Skill？”

第 2 步：规划可复用内容

针对每个示例，分析：

1. 如何从头开始执行
2. 哪些脚本、参考资料和资源有助于重复执行

示例分析：

• pdf-editor，用于“旋转此 PDF” → 需要 scripts/rotate_pdf.py
• frontend-webapp-builder → 需要 assets/hello-world/ 模板
• big-query 技能 → 需要 references/schema.md，用于记录表结构

第 3 步：初始化技能

创建技能目录结构：

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)

第 4 步：编写 SKILL.md

• 使用祈使式/不定式（“要实现 X，请执行 Y”）
• 回答：用途是什么？何时使用？如何使用随附资源？
• 引用所有脚本和参考资料，让 Claude 知道它们的存在

第 5 步：验证并打包

# Validate skill structure and content
python scripts/validate_skill.py <path>

# Check for self-contained tool completeness
python scripts/check_self_contained.py <path>

第 6 步：迭代

在实际使用后：

1. 留意遇到的困难或效率低下之处
2. 确定应如何更新 SKILL.md 或随附资源
3. 实施更改并再次测试

---

常见工作流

根据专业知识创建技能：

1. 确定范围：具备哪些专业知识？关键词是什么？哪些内容不处理？
2. 编写包含关键词和“不处理”条款的描述
3. 添加你观察到的反模式
4. 彻底测试激活情况

调试激活问题（流程图）：

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

运行 python scripts/test_activation.py <path> 进行验证

递归自我改进（使用此技能改进技能）：

1. 运行 python scripts/validate_skill.py <path> → 获取验证报告
2. 运行 python scripts/check_self_contained.py <path> → 检查工具完整性
3. 先处理错误，再处理警告，最后处理建议
4. 重新运行验证，直到没有问题
5. 在 CHANGELOG.md 中记录所做的改进

工具权限

指南：

• 只读技能：Read,Grep,Glob
• 文件修改器：Read,Write,Edit
• 构建集成：Read,Write,Bash(npm:*,git:*)
• ⚠️ 切勿：对不可信技能开放不受限制的 Bash

成功指标

指标	目标
正确激活率	>90%
误报率	<5%
Token 用量	<5k（典型值）

参考文件

文件	内容
references/antipatterns.md	领域行话和反模式目录，含案例研究
references/shibboleths.md	专家与新手的知识模式
references/validation-checklist.md	完整的审查与测试指南
references/self-contained-tools.md	脚本、MCP 服务和子 Agent 的实现模式
references/scoring-rubric.md	技能量化评估（0-10 分）
references/skill-composition.md	跨技能依赖关系和组合模式
references/skill-lifecycle.md	维护、版本控制和弃用指南
references/mcp_vs_scripts.md	架构决策指南：Skills、Agents、MCPs 与 Scripts

---

此技能指导：技能创建 | 技能审计 | 反模式检测 | 渐进式披露 | 领域专业知识编码