Skills工程实践1

1.从CLAUDE.md到Skills：知识的两个维度

• 一个Skill是一个包含指令的文件夹，被打包成一个简单的目录结构，用来‘教’Claude如何处理特定任务或工作流。
  第一个是“文件夹”——从“字符串”到“工程化”。
  第二个是“教”——从“约束”到“内化”。

2 解剖一个Skill：骨骼与纹理

点击查看代码

api-doc-generator/ ← Skill 名称（kebab-case，短横线分隔，像文件名一致清晰）
├── SKILL.md ← 【核心骨架】必需的主技能文件（注意：大小写必须精确匹配）
├── scripts/ ←【手脚】可选的可执行脚本，让Skill能主动“做”事
│ └── detect-routes.py ← 如自动扫描代码库发现路由
├── reference/ ←【记忆库】可选的按需加载参考文档，不占常驻内存
│ ├── openapi-patterns.md ← 只有生成文档时才读取的规范
│ └── error-codes.md ← 只有处理错误时才查阅的码表
└── templates/ ← 【模具】可选的输出模板，确保产出格式统一
└── endpoint-doc.md ← 定义API文档长什么样

• 文件名：SKILL.md——唯一的“触发器”。
• 目录名：kebab-case——跨平台的“通用语”。
• 禁入README.md——纯净的“指令空间”。
• 命名中立：拒绝“claude”或“anthropic”。

2.2 YAML前置元数据：Skill的“身份证”

点击查看代码

---
name: api-doc-generator # 【唯一标识符】最多64个字符，若省略则默认使用目录名
description: >- # 【触发描述】最多1024个字符，若省略则默认使用 SKILL.md 正文第一段
  Generate API documentation from source code. Use when the user asks to
  "write API docs", "document endpoints", or "create OpenAPI specs".
  Supports Express, FastAPI, and Spring Boot.
argument-hint: "[source directory] [output format]" # 【参数提示】在 "/" 菜单中显示
disable-model-invocation: true # 【禁用模型自动调用】true 时禁止 Claude 自动调用，需手动 /skill-name 触发
user-invocable: false # 【用户可调用性】false 时从 "/" 菜单隐藏，但 Claude 仍可自动调用
allowed-tools: # 【工具白名单】精确控制 Skill 执行时可调用的工具及权限范围
  - Read
  - Grep
  - Glob
  - Write
  - Bash(python:*)
model: haiku # 【指定模型】建议简单任务使用 Haiku 以提升响应速度并降低成本
context: fork # 【执行上下文】fork 模式在隔离子智能体中执行，避免污染主对话上下文
agent: Explore # 【子智能体类型】context=fork 时生效，可选：Explore / Plan / general-purpose / 自定义
hooks: # 【生命周期事件钩子】仅在 Skill 激活状态下生效
  PreToolUse:
    - matcher: Bash
      hooks:
        - command: echo "$TOOL_INPUT" >> audit.log
---

• 身份字段（触发机制）：包含name、description、argument-hint。
• 权限字段（权限控制）：包含disable-model-invocation、user-invocable、allowedtools、model。
• 执行字段（运行时环境）：包含context、agent、hooks。

3 渐进式披露：知识的投资回报率

3.1 图书馆模型

• 三层渐进式披露模型

3.2 description的预算机制

• Claude Code官方的规则：description总预算上限为上下文窗口总量的2%，若未指定或计算异常，默认固定为16 000个字符。

4 触发机制：Claude Code如何抉择Skills的调用

4.1 双通道激活机制

1.显式调用

• 用户在对话中输入/skill-name，Claude Code即刻加载并执行对应Skill。

2.语义匹配

• Claude在深入理解用户意图后，自主研判哪个Skill与当前任务最为契合，从而自动加载。

4.2 description——Skills的灵魂

• Claude Code推荐的description撰写结构公式如下。
  [功能定义]（做什么）+[触发场景]（何时用）+[核心能力]（能做什么）

点击查看代码

# 过于模糊，导致Claude无法判断使用时机
description: Helps with projects.
# 过于技术化，缺失用户视角的触发关键词
description: Implements the Project entity model with hierarchical relationships.
# 仅描述功能，未界定触发场景
description: Generates API documentation.
# 正确示范：特点是表述清晰、涵盖具体触发场景、详述核心能力
description: Generate API documentation from Express, FastAPI, or Spring Boot source code.
Use when user asks to "write API docs", "document endpoints", "create OpenAPI specs", or
mentions "Swagger". Supports route detection, request/response schema extraction, and
authentication requirement marking.

第1步，定义核心能力（What）：用一句话精准概括该Skill“能做什么”，确定其基本功能定位。
第2步，明确触发场景（When）：使用Use when user...句式，详细列举各种可能触发该Skill的用户指令、短语或关键词，提高语义匹配的命中率。
第3步，划定排除范围（Not For）：（可选但推荐）如果该Skill容易被误触发，务必加上Not for...，明确指出其不适用的场景，以优化决策的准确性。

4.3 防止过触发与欠触发

1.欠触发
2.过触发

4.4 参考型Skill与任务型Skill：两种Skill哲学

1.参考型Skill 配置：默认行为。
2.任务型Skill 配置：显式设置disable-model-invocation: true。

5 SKILL.md正文：是路由器，不是仓库

5.1 路由器思维

• Quick Reference

分析类型	触发关键词	参考资源
收入分析（Revenue）	收入、营收、销售额	reference/revenue.md
成本分析（Cost）	成本、费用、支出	reference/costs.md
盈利分析（Profitability）	利润、毛利率、净利率	reference/profitability.md

5.2 契约式引用

• 确保Claude清晰知晓3个核心要素：触发时机（何时加载）、资源位置（去哪查找）以及预期产出（获取何物）。

点击查看代码

# 引用模式对比：弱引用 vs 契约式引用

## 弱引用（缺乏上下文）

> See `reference/revenue.md` for more details.

**问题诊断：**
- Claude 无法判断**何时**该加载此文件
- 缺乏明确的**行动指令**
- 没有说明文件中包含**什么内容**

---

## 契约式引用（明确条件 + 路径 + 内容预期）

### Revenue Analysis

**触发条件：** When the user asks about revenue growth, ARPU, or revenue composition:

**执行动作：** → Load `reference/revenue.md` for calculation formulas and industry benchmarks.

**优势：**
- **明确触发条件**：定义了具体的关键词和场景
- **指定文件路径**：精确指向目标资源
- **声明内容预期**：告知模型文件中包含计算公式和行业基准

• 这一设计理念与子智能体流水线中的“交接契约”一脉相承：下游消费者不仅需要知道上游的位置，更必须明确上游能提供什么。

5.3 500行法则

• Claude Code建议将SKILL.md的篇幅控制在500行以内。
• 重构信号对策
  大段公式或规范说明移至reference/目录
  多个完整示例（单个超过30行）移至examples/目录
  多个输出模板移至templates/目录
  可独立执行的逻辑封装为scripts/脚本
  多个平行的功能模块考虑拆分为多个独立的Skill

6 allowed-tools：知识约束行动

• allowed-tools是Skills安全架构中的核心字段。它不仅仅是一份权限清单，更体现了一项深层设计原则：知识应当约束行动。

6.1 权限设计模板

点击查看代码

# 审计类 Skill：严格只读
allowed-tools:
  - Read
  - Grep
  - Glob

# 生成类 Skill：可写不可改
allowed-tools:
  - Read
  - Grep
  - Glob
  - Write

# 分析类 Skill：只读 + 特定脚本
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(python:*)

# 执行类 Skill：受控命令白名单
allowed-tools:
  - Read
  - Bash(git status:*)
  - Bash(git add:*)
  - Bash(git commit:*)
  - Bash(npm test:*)

6.2 Bash的精细控制语法

• Bash工具支持通过前缀匹配机制，实现对可执行命令的细粒度管控。其核心语法为Bash(prefix:)，其中prefix指定允许的命令前缀，作为通配符代表后续参数。

点击查看代码

Bash(git:*) # 允许所有以git开头的子命令
Bash(git log:*) # 仅允许git log及其参数，禁止git push等危险操作
Bash(npm test:*) # 仅允许运行测试命令，防止误执行npm install或npm publish Bash(python:*) #
允许所有Python脚本执行
Bash(./scripts/*:*) # 允许执行scripts/目录下的特定脚本

• 当Claude尝试执行Bash命令时，系统会进行前置校验。
  • 提取前缀：获取用户请求执行的完整命令字符串。
  • 匹配规则：检查该命令是否以配置的prefix开头。

• 执行决策：若匹配成功，则放行执行；若匹配失败，则直接拒绝，并返回权限错误。

• 遵循权限最小化原则（Principle of Least Privilege）是构建安全Skills的基石。以下是关于allowed-tools配置的正反案例对比。

点击查看代码

# 精确授权：只明确列出任务所需的具体命令子集
# 场景：代码提交 Skill
# 策略：仅允许 status、add、commit 3 个特定子命令
allowed-tools:
  - "Bash(git status:*)"
  - "Bash(git add:*)"
  - "Bash(git commit:*)"

# 过度授权：使用全局通配符等同放弃所有防线
# 场景：错误的通用配置
# 风险：允许执行任意 Shell 命令（包括 rm -rf、curl 外发数据等）
allowed-tools:
  - "Bash(*)"