如果你把 Skill 当成“提示词模板”，那基本还停留在 1.0 阶段。

Anthropic 的 skill-creator 实际做的是另一件事：定义一种“可执行、可组合、可加载”的 Agent 能力单元（Capability Unit）。

这篇文章从源码层面，拆掉它的抽象，讲清楚三件事：

1. Skill 本质是什么（不是 prompt）
2. SKILL.md 为什么长这样（不是文档）
3. scripts / references 为什么必须存在（不是附属）

一、Skill 的本质：不是 Prompt，而是“受控执行环境”

先给一个更准确的定义：

Skill = 可触发的上下文片段 + 可选执行资源 + 明确边界条件

换句话说：

Skill ≈ Prompt Template + Tool Bundle + Lazy Loader

1.1 Skill 的执行模型（关键）

User Input
   ↓
Match(description)
   ↓
Load(SKILL.md)
   ↓
Reason()
   ├── need_knowledge → Load(references/)
   └── need_action    → Run(scripts/)

从 skill-creator 可以反推出一个隐式运行时模型：

flowchart TD
    A[User Input] --> B[Skill Matcher]
    B -->|匹配 description| C[Load SKILL.md]
    C --> D[Agent Reasoning]
    D -->|需要更多信息| E[Load references/]
    D -->|需要执行| F[Run scripts/]

核心点：

• Skill 不是一直在上下文里
• Skill 是按需加载的模块
• Skill 是分层加载的（lazy load）

1.2 三层加载 = Token 预算调度系统

skill-creator 最重要的一句话：

context window is a public good

翻译成工程语言：

Context Window = Shared Memory (多租户系统)

所以 Skill 的设计，本质是：

如何在有限 token 内实现最大能力密度

三层结构：

二、SKILL.md 本质：不是说明书，而是“控制程序”

很多人误解 SKILL.md 是文档，其实它更接近：

Declarative Control Program

2.1 YAML = Skill 的“路由层”

---
name: skill-creator
description: |
  Guide for creating effective skills...
---

这里的关键不是 metadata，而是：

description = 触发条件 DSL（Domain Specific Language）

Agent 在做的其实是：

def should_trigger(skill, user_input):
    return semantic_match(skill.description, user_input)

👉 所以 description 必须：

• 覆盖“功能”
• 覆盖“触发语义”
• 覆盖“边界条件”

2.2 Body = Imperative DSL（指令语言）

skill-creator 强制使用祈使句，本质原因不是风格，而是：

减少推理分支（branching factor）

对比：

❌ You should run the script
→ 需要判断 should 不 should

✅ Run the script
→ 直接执行

等价于：

# bad
if should_run():
    run()

# good
run()

2.3 SKILL.md 的真实结构

抽象成代码结构：

class Skill:
    def __init__(self):
        self.trigger = description
        self.controller = instructions
        self.resources = {
            "scripts": [],
            "references": []
        }

三、7 大原则的“底层解释”（不是表面总结）

下面不是复述，而是解释它们为什么存在。

原则 1：Concise = 信息熵最大化

不是“简洁”，而是：

Maximize (Useful Information / Token)

换算成工程指标：

Information Density ↑
Redundancy ↓

典型优化：

❌ 解释 + 示例
✅ 只留示例

因为：

Example > Explanation

原则 2：自由度 = 搜索空间控制

Skill 实际是在控制 Agent 的搜索空间：

High freedom → 大搜索空间 → 灵活但不稳定
Low freedom → 小搜索空间 → 稳定但僵化

映射：

原则 3：渐进式披露 = Lazy Evaluation

本质就是：

def load_skill():
    load(metadata)
    if triggered:
        load(body)
    if needed:
        load(resources)

这和：

• 数据库 lazy loading
• 虚拟内存分页

是一个思路。

原则 4：不要 README = 避免 Context Pollution

多余文件的本质问题：

Noise ↑ → Attention Dilution ↑ → Performance ↓

Agent 不会“忽略无关信息”，它只会：

被污染

原则 5：description = 唯一入口

Skill 是否触发，只看 description：

Body 再好，如果 description 写烂 = 永远不会触发

所以：

description ≈ API Gateway

原则 6：祈使句 = 降低推理成本

本质：

减少 token 内的决策节点

原则 7：不重复 = 单一信息源（SSOT）

Single Source of Truth

否则：

冲突 → agent 不确定 → 输出退化

四、Skill 的代码层设计模式（关键）

skill-creator 其实隐含了三种模式：

4.1 Workflow Pattern（流程编排）

User Request → Step1 → Step2 → Step3

在 SKILL.md 里表现为：

1. Extract text
2. Analyze structure
3. Generate output

4.2 Tool Wrapper Pattern（工具封装）

例如：

python scripts/convert_format.py input.docx output.pdf

本质是：

def tool(input):
    return subprocess.run(...)

4.3 Reference Injection Pattern

See references/ooxml-reference.md

等价于：

if need_deep_knowledge:
    load(reference)

五、从 docx Skill 看“正确的工程写法”

你给的 docx-processor，其实是一个非常标准的 Skill 工程。

我们从代码层面看它的优点。

5.1 CLI 设计是关键

if len(sys.argv) != 3:
    print('usage...')
    sys.exit(1)

这是典型：

Fail Fast + Deterministic Interface

5.2 subprocess 调用 = Tool 抽象

cmd = ['pandoc', input_path, '-o', output_path]

本质：

Skill 不实现能力 → 调用系统能力

5.3 OOXML 参考文件的意义

不是文档，而是：

On-demand Knowledge Base

当 agent 需要：

低级格式操作（XML）

才加载。

5.4 extract_text 的设计点

for table in doc.tables:

说明：

Skill 必须覆盖“隐含结构”

否则 agent 会漏信息。

六、真正的 Skill 设计 Checklist（工程版）

不是理论，直接给工程 checklist：

1. Trigger 层（description）

• 是否覆盖所有用户表达方式？
• 是否包含“何时不用”？
• 是否避免模糊词？

2. Control 层（SKILL.md）

• 是否全是 imperative？
• 是否有明确步骤？
• 是否避免解释性语言？

3. Execution 层（scripts）

• 是否可 CLI 调用？
• 是否 deterministic？
• 是否有错误处理？

4. Knowledge 层（references）

• 是否只在必要时加载？
• 是否避免重复？

5. Context 控制

• SKILL.md 是否 < 500 行？
• 是否把复杂逻辑外移？

七、一个关键结论

skill-creator 真正教你的不是：

“怎么写 Skill”

而是：

如何为 AI 设计一个最小认知负担的执行环境

或者更直白一点：

Skill = 给模型“减负”的工程体系

如果你接下来想更硬核一点，我们可以继续往下拆两层：

• 👉 如何设计“可组合 Skill”（Skill chaining / DAG）
• 👉 如何把 Skill 做成“Agent OS”（类似插件系统）

这两块才是现在 Cursor / Claude Code 真正的竞争核心。