工具定义了能力边界——没有 bash 工具，模型就无法执行命令。Skills 注入知识——没有前端设计 Skill，模型会产生通用的 UI。

公式：

General Agent + Excellent Skill = Domain Expert Agent

同一个 Claude 模型，加载不同的 Skills，就变成了不同的专家。

Skill 中的三种知识类型

评估时，对每个部分进行分类：

Skill 设计的艺术在于最大化专家内容，谨慎使用激活内容，并无情地消除冗余内容。

评估维度（总分 120 分）

D1: 知识增量（20 分）——核心维度

最重要的维度。Skill 是否添加了真正的专家知识？

危险信号（立即得分 ≤5）：

• "什么是 [基本概念]" 部分
• 标准操作的分步教程
• 解释如何使用常见库
• 通用最佳实践（"编写整洁的代码"、"处理错误"）
• 行业标准术语的定义

积极信号（高知识增量的指标）：

• 非显而易见选择的决策树（"当 X 失败时，尝试 Y，因为 Z"）
• 只有专家才知道的权衡取舍（"A 更快，但 B 能处理边界情况 C"）
• 来自实际经验的边界情况
• "绝对不要做 X，因为 [非显而易见的原因]"
• 特定领域的思维框架

评估问题：

1. 对于每个部分，问："Claude 已经知道这个了吗？"
2. 如果是在解释某事，问："这是在向 Claude 解释，还是为 Claude 解释？"
3. 统计专家内容、激活内容和冗余内容的段落数量

D2: 思维方式 + 适当的流程（15 分）

Skill 是否在传授必要的特定领域流程的同时，也传递了专家的思维模式？

专家和新手的区别不在于"知道如何操作"——而在于"如何思考问题"。但当 Claude 缺乏特定领域的流程知识时，仅有思维模式是不够的。

关键区别：

什么算作有价值的流程：

• Claude 未训练过的工作流（新工具、专有系统）
• 非显而易见的正确顺序（例如，"在打包之前验证，而不是之后"）
• 容易遗漏的关键步骤（例如，"编辑后必须重新计算公式"）
• 特定领域的序列（例如，MCP 服务器的 4 阶段开发流程）

什么算作冗余流程：

• 通用文件操作（打开、读取、写入、保存）
• 标准编程模式（循环、条件语句、错误处理）
• 有良好文档记录的常见库用法

专家思维模式示例：

Before [action], ask yourself:
- **Purpose**: What problem does this solve? Who uses it?
- **Constraints**: What are the hidden requirements?
- **Differentiation**: What makes this solution memorable?

有价值的特定领域流程示例：

### Redlining Workflow (Claude wouldn't know this sequence)
1. Convert to markdown: `pandoc --track-changes=all`
2. Map text to XML: grep for text in document.xml
3. Implement changes in batches of 3-10
4. Pack and verify: check ALL changes were applied

冗余的通用流程示例：

Step 1: Open the file
Step 2: Find the section
Step 3: Make the change
Step 4: Save and test

测试方法：

1. 它是否告诉 Claude 思考什么？（思维模式）
2. 它是否告诉 Claude 如何做它不知道的事情？（特定领域流程）

一个好的 Skill 在需要时两者都提供。

D3: 反模式质量（15 分）

Skill 是否有有效的"绝对不要"列表？

为什么这很重要：专家知识的一半在于知道不要做什么。资深设计师看到白色背景上的紫色渐变会本能地感到不适——"太像 AI 生成的了。"这种对"绝对不要做什么"的直觉来自于踩过无数的坑。

Claude 没有踩过这些坑。它不知道 Inter 字体被过度使用，不知道紫色渐变是 AI 生成内容的标志。好的 Skills 必须明确说明这些"绝对不要做的事"。

专家反模式（具体 + 原因）：

NEVER use generic AI-generated aesthetics like:
- Overused font families (Inter, Roboto, Arial)
- Cliched color schemes (particularly purple gradients on white backgrounds)
- Predictable layouts and component patterns
- Default border-radius on everything

弱反模式（模糊，无推理）：

Avoid making mistakes.
Be careful with edge cases.
Don't write bad code.

测试方法：专家阅读反模式列表后会说"是的，我吃过亏才学到这个"吗？还是他们会说"这对每个人来说都是显而易见的"？

D4: 规范合规性——特别是描述（15 分）

Skill 是否遵循官方格式要求？特别关注描述质量。

Frontmatter 要求：

• name：小写，仅限字母数字和连字符，≤64 个字符
• description：最关键的字段——决定 Skill 是否会被使用

为什么描述是最重要的字段：

┌─────────────────────────────────────────────────────────────────────┐
│  SKILL ACTIVATION FLOW                                              │
│                                                                     │
│  User Request → Agent sees ALL skill descriptions → Decides which  │
│                 (only descriptions, not bodies!)     to activate    │
│                                                                     │
│  If description doesn't match → Skill NEVER gets loaded            │
│  If description is vague → Skill might not trigger when it should  │
│  If description lacks keywords → Skill is invisible to the Agent   │
└─────────────────────────────────────────────────────────────────────┘

残酷的事实：内容完美但描述不佳的 Skill 是无用的——它永远不会被激活。描述是告诉 Agent"在这些情况下使用我"的唯一机会。

描述必须回答三个问题：

1. WHAT：这个 Skill 做什么？（功能）
2. WHEN：在什么情况下应该使用它？（触发场景）
3. KEYWORDS：哪些术语应该触发这个 Skill？（可搜索的术语）

优秀的描述（包含所有三个要素）：

description: "Comprehensive document creation, editing, and analysis with support
for tracked changes, comments, formatting preservation, and text extraction.
When Claude needs to work with professional documents (.docx files) for:
(1) Creating new documents, (2) Modifying or editing content,
(3) Working with tracked changes, (4) Adding comments, or any other document tasks"

分析：

• WHAT：创建、编辑、分析、跟踪更改、评论
• WHEN："当 Claude 需要处理...时，用于：(1)... (2)... (3)..."
• KEYWORDS：.docx 文件、跟踪更改、专业文档

差的描述（缺少要素）：

description: "处理文档相关功能"

问题：

• WHAT：模糊（"文档相关功能"——具体是什么？）
• WHEN：缺失（Agent 应该在什么时候使用这个？）
• KEYWORDS：缺失（没有".docx"，没有具体场景）

另一个差的例子：

description: "A helpful skill for various tasks"

这是无用的——Agent 不知道何时激活它。

描述质量检查清单：

• 列出具体能力（不仅仅是"帮助处理 X"）
• 包含明确的触发场景（"当...时使用"、"当用户要求..."）
• 包含可搜索的关键词（文件扩展名、领域术语、动作动词）
• 足够具体，让 Agent 确切知道何时使用
• 包含必须使用此 Skill 的场景（不仅仅是"可以使用"）

D5: 渐进式披露（15 分）

Skill 是否实现了适当的内容分层？

Skill 加载有三个层次：

Layer 1: Metadata (always in memory)
         Only name + description
         ~100 tokens per skill

Layer 2: SKILL.md Body (loaded after triggering)
         Detailed guidelines, code examples, decision trees
         Ideal: < 500 lines

Layer 3: Resources (loaded on demand)
         scripts/, references/, assets/
         No limit

对于有参考资料目录的 Skills，检查加载触发器质量：

加载问题：

Loading too little ◄─────────────────────────────────► Loading too much
- References sit unused                    - Wastes context space
- Agent doesn't know when to load          - Irrelevant info dilutes key content
- Knowledge is there but never accessed    - Unnecessary token overhead

好的加载触发器（嵌入在工作流中）：

### Creating New Document

**MANDATORY - READ ENTIRE FILE**: Before proceeding, you MUST read
[`docx-js.md`](docx-js.md) (~500 lines) completely from start to finish.
**NEVER set any range limits when reading this file.**

**Do NOT load** `ooxml.md` or `redlining.md` for this task.

差的加载触发器（仅列出）：

## References
- docx-js.md - for creating documents
- ooxml.md - for editing
- redlining.md - for tracking changes

对于简单的 Skills（无参考资料，<100 行）：根据简洁性和自包含性评分。

D6: 自由度校准（15 分）

对于任务的脆弱性，具体的程度是否合适？

不同的任务需要不同级别的约束。这是关于将自由度与脆弱性相匹配。

自由度谱系：

高自由度（基于文本的指导）：

Commit to a BOLD aesthetic direction. Pick an extreme: brutally minimal,
maximalist chaos, retro-futuristic, organic natural...

中等自由度（伪代码或参数化）：

Review priority:
1. Security vulnerabilities (must fix)
2. Logic errors (must fix)
3. Performance issues (should fix)
4. Maintainability (optional)

低自由度（特定脚本，精确步骤）：

**MANDATORY**: Use exact script in `scripts/create-doc.py`
Parameters: --title "X" --author "Y"
Do NOT modify the script.

测试方法：问"如果 Agent 犯了一个错误，后果是什么？"

• 后果严重 → 低自由度
• 后果轻微 → 高自由度

D7: 模式识别（10 分）

Skill 是否遵循已建立的官方模式？

通过分析 17 个官方 Skills，我们识别出 5 种主要设计模式：

模式选择指南：

D8: 实际可用性（15 分）

Agent 能否实际有效地使用这个 Skill？

检查：

• 决策树：对于多路径场景，是否有关于选择哪条路径的清晰指导？
• 代码示例：它们真的有效吗？还是会导致崩溃的伪代码？
• 错误处理：如果主要方法失败怎么办？是否提供了备用方案？
• 边界情况：是否涵盖了不常见但现实的场景？
• 可操作性：Agent 是否可以立即行动，还是需要自己想办法？

良好的可用性（决策树 + 备用方案）：

| Task | Primary Tool | Fallback | When to Use Fallback |
|------|-------------|----------|----------------------|
| Read text | pdftotext | PyMuPDF | Need layout info |
| Extract tables | camelot-py | tabula-py | camelot fails |

**Common issues**:
- Scanned PDF: pdftotext returns blank → Use OCR first
- Encrypted PDF: Permission error → Use PyMuPDF with password

差的可用性（模糊）：

Use appropriate tools for PDF processing.
Handle errors properly.
Consider edge cases.

评估时绝对不要做的事

• 绝对不要仅仅因为它"看起来很专业"或格式良好就给高分
• 绝对不要忽视令牌浪费——每个冗余段落都应导致扣分
• 绝对不要被长度所打动——一个 43 行的 Skill 可能优于一个 500 行的 Skill
• 绝对不要跳过对决策树的心理测试——它们是否真的能导向正确的选择？
• 绝对不要以"但它提供了有用的上下文"为由来原谅对基础知识的解释
• 绝对不要忽视缺失的反模式——如果没有"绝对不要"列表，这是一个重大缺陷
• 绝对不要假设所有流程都有价值——区分特定领域流程和通用流程
• 绝对不要低估描述字段——描述差 = Skill 永远不会被使用
• 绝对不要把"何时使用"的信息只放在正文中——Agent 在加载前只能看到描述

评估协议

步骤 1：第一遍——知识增量扫描

完整阅读 SKILL.md，并对每个部分提问：

"Claude 已经知道这个了吗？"

将每个部分标记为：

• [E] 专家：Claude 确实不知道这个——增值
• [A] 激活：Claude 知道但简短的提醒有用——可接受
• [R] 冗余：Claude 肯定知道这个——应该删除

计算粗略比例：E:A:R

• 好的 Skill：>70% 专家，<20% 激活，<10% 冗余
• 一般的 Skill：40-70% 专家，高激活
• 差的 Skill：<40% 专家，高冗余

步骤 2：结构分析

[ ] Check frontmatter validity
[ ] Count total lines in SKILL.md
[ ] List all reference files and their sizes
[ ] Identify which pattern the Skill follows
[ ] Check for loading triggers (if references exist)

步骤 3：为每个维度评分

对于 8 个维度中的每一个：

1. 找到具体证据（引用相关行）
2. 用一句话的理由分配分数
3. 如果分数 < 最大值，注明具体的改进点

步骤 4：计算总分和等级

Total = D1 + D2 + D3 + D4 + D5 + D6 + D7 + D8
Max = 120 points

等级标准（基于百分比）：

步骤 5：生成报告

# Skill Evaluation Report: [Skill Name]

## Summary
- **Total Score**: X/120 (X%)
- **Grade**: [A/B/C/D/F]
- **Pattern**: [Mindset/Navigation/Philosophy/Process/Tool]
- **Knowledge Ratio**: E:A:R = X:Y:Z
- **Verdict**: [One sentence assessment]

## Dimension Scores

| Dimension | Score | Max | Notes |
|-----------|-------|-----|-------|
| D1: Knowledge Delta | X | 20 | |
| D2: Mindset vs Mechanics | X | 15 | |
| D3: Anti-Pattern Quality | X | 15 | |
| D4: Specification Compliance | X | 15 | |
| D5: Progressive Disclosure | X | 15 | |
| D6: Freedom Calibration | X | 15 | |
| D7: Pattern Recognition | X | 10 | |
| D8: Practical Usability | X | 15 | |

## Critical Issues
[List must-fix problems that significantly impact the Skill's effectiveness]

## Top 3 Improvements
1. [Highest impact improvement with specific guidance]
2. [Second priority improvement]
3. [Third priority improvement]

## Detailed Analysis
[For each dimension scoring below 80%, provide:
- What's missing or problematic
- Specific examples from the Skill
- Concrete suggestions for improvement]

常见失败模式

模式 1：教程式

Symptom: Explains what PDF is, how Python works, basic library usage
Root cause: Author assumes Skill should "teach" the model
Fix: Claude already knows this. Delete all basic explanations.
     Focus on expert decisions, trade-offs, and anti-patterns.

模式 2：堆砌式

Symptom: SKILL.md is 800+ lines with everything included
Root cause: No progressive disclosure design
Fix: Core routing and decision trees in SKILL.md (<300 lines ideal)
     Detailed content in references/, loaded on-demand

模式 3：孤立的参考资料

Symptom: References directory exists but files are never loaded
Root cause: No explicit loading triggers
Fix: Add "MANDATORY - READ ENTIRE FILE" at workflow decision points
     Add "Do NOT Load" to prevent over-loading

模式 4：复选框式流程

Symptom: Step 1, Step 2, Step 3... mechanical procedures
Root cause: Author thinks in procedures, not thinking frameworks
Fix: Transform into "Before doing X, ask yourself..."
     Focus on decision principles, not operation sequences

模式 5：模糊警告

Symptom: "Be careful", "avoid errors", "consider edge cases"
Root cause: Author knows things can go wrong but hasn't articulated specifics
Fix: Specific NEVER list with concrete examples and non-obvious reasons
     "NEVER use X because [specific problem that takes experience to learn]"

模式 6：隐形 Skill

Symptom: Great content but skill rarely gets activated
Root cause: Description is vague, missing keywords, or lacks trigger scenarios
Fix: Description must answer WHAT, WHEN, and include KEYWORDS
     "Use when..." + specific scenarios + searchable terms

Example fix:
BAD:  "Helps with document tasks"
GOOD: "Create, edit, and analyze .docx files. Use when working with
       Word documents, tracked changes, or professional document formatting."

模式 7：位置错误

Symptom: "When to use this Skill" section in body, not in description
Root cause: Misunderstanding of three-layer loading
Fix: Move all triggering information to description field
     Body is only loaded AFTER triggering decision is made

模式 8：过度工程化

Symptom: README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, CONTRIBUTING.md
Root cause: Treating Skill like a software project
Fix: Delete all auxiliary files. Only include what Agent needs for the task.
     No documentation about the Skill itself.

模式 9：自由度不匹配

Symptom: Rigid scripts for creative tasks, vague guidance for fragile operations
Root cause: Not considering task fragility
Fix: High freedom for creative (principles, not steps)
     Low freedom for fragile (exact scripts, no parameters)

快速参考检查清单

┌─────────────────────────────────────────────────────────────────────────┐
│  SKILL EVALUATION QUICK CHECK                                           │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  KNOWLEDGE DELTA (most important):                                      │
│    [ ] No "What is X" explanations for basic concepts                   │
│    [ ] No step-by-step tutorials for standard operations                │
│    [ ] Has decision trees for non-obvious choices                       │
│    [ ] Has trade-offs only experts would know                           │
│    [ ] Has edge cases from real-world experience                        │
│                                                                         │
│  MINDSET + PROCEDURES:                                                  │
│    [ ] Transfers thinking patterns (how to think about problems)        │
│    [ ] Has "Before doing X, ask yourself..." frameworks                 │
│    [ ] Includes domain-specific procedures Claude wouldn't know         │
│    [ ] Distinguishes valuable procedures from generic ones              │
│                                                                         │
│  ANTI-PATTERNS:                                                         │
│    [ ] Has explicit NEVER list                                          │
│    [ ] Anti-patterns are specific, not vague                            │
│    [ ] Includes WHY (non-obvious reasons)                               │
│                                                                         │
│  SPECIFICATION (description is critical!):                              │
│    [ ] Valid YAML frontmatter                                           │
│    [ ] name: lowercase, ≤64 chars                                       │
│    [ ] description answers: WHAT does it do?                            │
│    [ ] description answers: WHEN should it be used?                     │
│    [ ] description contains trigger KEYWORDS                            │
│    [ ] description is specific enough for Agent to know when to use     │
│    [ ] Includes scenarios where this skill MUST be used (not just "can be used")
│                                                                         │
│  STRUCTURE:                                                             │
│    [ ] SKILL.md < 500 lines (ideal < 300)                               │
│    [ ] Heavy content in references/                                     │
│    [ ] Loading triggers embedded in workflow                            │
│    [ ] Has "Do NOT Load" for preventing over-loading                    │
│                                                                         │
│  FREEDOM:                                                               │
│    [ ] Creative tasks → High freedom (principles)                       │
│    [ ] Fragile operations → Low freedom (exact scripts)                 │
│                                                                         │
│  USABILITY:                                                             │
│    [ ] Decision trees for multi-path scenarios                          │
│    [ ] Working code examples                                            │
│    [ ] Error handling and fallbacks                                     │
│    [ ] Edge cases covered                                               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

元问题

评估任何 Skill 时，始终回到这个基本问题：

"这个领域的专家，看到这个 Skill，会说： '是的，这捕捉了我花了多年才学到的知识'吗？"

如果答案是肯定的 → Skill 具有真正的价值。如果答案是否定的 → 它只是在压缩 Claude 已经知道的东西。

最好的 Skills 是压缩的专家大脑——它们将设计师 10 年的美学积累压缩成 43 行，或将文档专家的操作经验压缩成一个 200 行的决策树。

被压缩的必须是 Claude 没有的东西。否则，就是垃圾压缩。

自我评估说明

这个 Skill（skill-judge）本身应该通过评估：

• 知识增量：提供 Claude 自己不会生成的特定评估标准
• 思维方式：塑造如何思考 Skill 质量，而不仅仅是检查清单项目
• 反模式："评估时绝对不要做的事"部分包含具体的禁忌
• 规范：有效的 frontmatter 和全面的描述
• 渐进式披露：自包含，无需外部参考资料
• 自由度：适合评估任务的中等自由度
• 模式：遵循带有决策框架的工具模式
• 可用性：清晰的协议、报告模板、快速参考

将此 Skill 与自身进行对比评估，作为校准练习。

每周安装次数

145

仓库

davila7/claude-…emplates

GitHub 星标

22.6K

首次出现

Jan 25, 2026

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

opencode120

claude-code118

gemini-cli112

codex108

cursor103

github-copilot101