Skill的背景
#

每个公司每个团队都与自己的一套规范，例如代码风格规范、API设计规范、安全审查清单规范、部署流程规范，这些规则并不复杂，但是数量很多。开发者通常不可能将他们全部记忆下来，大部分工程师的做法是：需要时再查阅。

如果我们把 Claude 当作真正的工程助手，它也会面临同样的问题。最直接的做法，是把所有团队规范写进 CLAUDE.md，让模型每次对话都读取这些内容。短期看这是可行的。但当知识规模扩大到几十页甚至上百页时，问题就出现了——每一次对话都在为“可能用不到的知识”支付上下文成本。这不仅消耗 token，更重要的是，它会稀释模型的注意力。真正需要用到的规则，反而淹没在冗余信息里。

Skills的出现解决了这一问题。Skills 并不是简单的“能力扩展机制”，它本质上是一种按需加载的认知结构。与其把所有知识常驻在上下文中，不如把它们封装成可独立触发的能力单元。当模型判断当前任务涉及某个特定领域时，再加载对应的知识与操作流程。Skills 解决的核心问题是，在有限的上下文窗口中，让 Agent 在正确的时刻拥有正确的领域知识。

对于企业来说，把专业流程、领域知识和行动判断封装成可复用的能力单元，然后让智能体按需加载和调用，这是一种让通用模型具备专业化、按需调用能力的通用设计模式。类似 Skills 的模块化能力已经被用于数据分析、校验、报告生成等任务，把自然语言指令转化成结构化的专业工作流；也有技术方案将企业组件库、开发规范等封装成“技能包”，让模型自动发现、理解并正确应用这些业务能力。

正因为“模型调度能力”和“可操作知识”的重要性，Skills 已经逐渐脱离了 Claude 的语境，成了 Agent 生态中的通用概念。“技能化”思路正在从 Claude 系统扩展到其他智能体平台，以及 AI 赋能的工程工具中。在 Claude 发布的 Agent Skills 公用仓库中，集成了大量可复用的能力。Coze 也推出了技能商店，为 Coze 智能体生态提供即插即用的能力组件。

Skill的类型
#

从工程角度，Skill 内容分为两类，参考型和任务型。参考型 Skill 影响“怎么做”，任务型 Skill 决定“做什么”。前者是语义环境，后者是具体行动。

参考型
#

参考型 Skill 更像组织的行为规范层。它定义“在这个世界里，什么是正确的做法”——例如 API 设计标准、代码风格、错误处理约定。这类 Skill 通常由模型根据语义自动判断是否加载，它不主导行动，而是塑造行动的方式。它属于“世界规则”。

# 参考型——Claude 自动选择是否使用
name: api-conventions
description: API design patterns for this codebase. Use when writing or reviewing API endpoints.

任务型
#

任务型 Skill 则更像组织的操作流程层。它定义一次明确的行动——部署、发布、迁移、生成报告等。这类行为具有边界和风险，通常需要显式触发，因此常配合 disable-model-invocation 使用。它属于“世界事件”。

# 任务型——通常由用户手动触发
name: deploy
description: Deploy the application to production
disable-model-invocation: true

如何编写Skill
#

Skill放在哪
#

在讲如何编写skill前，因为Skill本质上就是一个个文件，先来讲讲Skill文件应该放在哪里。

其实你会发现，Claude Code的“套路”都差不多，无论是CALUDE.md、SubAgent、Skill都是放在.claude目录下，如果是个人级别的就在~/.claude下，如果是项目级别就在项目根目录的./claude下，因为日常开发都是在PC上，所以基本上就是用两种级别。（除非是那种使用云主机的公司…）。

同名优先级：Enterprise > Personal > Project。Plugin Skills 使用 plugin-name:skill-name 命名空间，不与其他级别冲突。

Skill与Command的关系
#

早期，斜杠命令 /Comands 和 Skills 是两个独立组件。但在新版 Claude Code 中，Commands 已合并到 Skills，成为 Skills 的子集。

因此，在 .claude/commands/review.md 和 .claude/skills/review/SKILL.md 两个不同目录的文件，都会创建 /review。Skills 目录的额外优势是支持辅助文件目录（模板、示例、脚本等）。如果同名 Skill 和 Command 共存，Skill 优先。

Skill内容
#

Skill必须放在.claude/skills/下面，且必须包含一个主文件，名称必须是Skill.md。

.claude/skills/api-conventions/ # skill 目录，名称即 skill 名
  └── SKILL.md # 主文件 

以一个项目级别的API设计规范为例，来说明下一个Skill应该包含哪些内容，下面是这个Skill的主文件Skill.md

---
name: api-conventions
description: 本项目的API设计模式与约定，涵盖RESTful URL命名、响应格式标准、异常处理及认证要求。编写/评审API接口、设计新API、确定请求/响应格式时请遵循本约定。
allowed-tools:
  - Read
  - Grep
  - Glob
---

# API Design Conventions

本项目的API设计标准，所有API接口开发均需遵循以下约定。

## URL Naming

- 资源使用复数名词：`/users`、`/orders`、`/products`
- 多词资源使用短横线命名法（kebab-case）：`/order-items`、`/user-profiles`
- 从属关系的资源使用嵌套路径：`/users/{id}/orders`
- 路径嵌套最多两级，超出时使用查询参数
- 筛选条件通过查询参数实现：`/orders?status=active&limit=20`

## Response Format

所有API响应必须遵循以下结构：

{
  "data": {},        // 成功时返回的业务数据
  "error": null,     // 错误时返回异常对象 { code, message, details }
  "meta": {          // 分页信息及接口元数据
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

## HTTP Status Codes

- 200: 成功返回数据
- 201: 资源创建成功
- 400: 请求参数不合法
- 401: 未进行身份认证
- 403: 无接口访问权限
- 404: 请求的资源不存在
- 422: 业务逻辑校验失败
- 500: 服务器内部未知异常

## Authentication

- 所有接口默认要求携带Bearer token，显式标记为公共接口的除外
- 公共接口必须通过`@public`注解标注并归档
- Token传递格式：`Authorization: Bearer <jwt-token>`

## Versioning

- API版本号嵌入URL路径：`/api/v1/users`
- 接口发生不兼容变更时，必须升级新版本

这个Skill.md文件有两个部分：

YAML frontmatter，是通过—包裹的元数据，👇会详细介绍原数据的各个字段
Markdown 正文，是技能的具体说明

为什么前面一直强调主文件？因为除了Skill.md外，一个Skill可以包含很多其他文件，例如模版文件、引用文件、数据文件，也可以包含代码脚本等其他任何需要的文件。（这一块等Skill渐进式披露机制再细讲）

Skill元数据
#

name ：最大 64 字符，只能使用小写字母、数字、连字符，推荐使用动名词形式：code-reviewing、api-documenting、bug-fixing。如果省略了这个字段（通常不大可能啦），则自动使用目录名（.claude/skills/code-reviewing/ → name 为 code-reviewing）
description：这是最重要的字段，是Skill的灵魂——它决定 Skill 何时被触发，它不是给人看的文档，而是给 Claude 看的触发器。Claude 选择是否激活一个 Skill，完全依赖于阅读 description。这不是关键词匹配，而是语义理解。虽然这个字段不是强制必须的，但还是建议每个Skill都配置上（就跟人没有灵魂一样，那这个人还有意义吗？）。此外description的语意必须明确，不能太过模糊，怎么才算明确？可以直接套用公式：description = [做什么] + [怎么做] + [什么时候用]

所有 Skill 的 description 会被加载到上下文中供 Claude 判断选择，默认总预算为 15,000 字符。如果你的 Skills 很多，导致 description 被截断，可以运行 /context 查看警告，并通过环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET 调大预算。
argument-hint ：自动补全提示，为用户提供参数格式提示，在输入 /skill-name 时系统会自动补全显示
disable-model-invocation ：默认为false，如果为true则代表不允许模型自动使用这个skill
user-invocabl：默认为false，如果为true则代表用户可以手动调用这个工具
allowed-tools：字段用来限制 Skills 被激活时 Claude 能使用的工具。Skills 支持的工具包括：

还可以更精细地控制 Bash 命令：
```
allowed-tools:
  - Bash(git:*)      # 只能执行 git 命令
  - Bash(npm test:*) # 只能执行 npm test z
```
context: 如果为fork，则在隔离的子代理中执行，不访问当前上下文
agent：指定子代理的类型（Explore、Plan或者自定义的代理）
model：指定执行的模型
hooks：Skill级别的 Hooks，可以为 Skill 定义仅在其生命周期内生效的 Hooks

这里有一个七步设计清单，可供参考：

动作是什么？ → 命名（commit、deploy、review）
谁能触发？   → disable-model-invocation: true
需要什么权限？→ allowed-tools 精确到命令级
启动时需要什么上下文？→ !`command` 预注入
执行过程需要什么安全网？→ hooks
输出量大不大？→ 大则 context: fork
用什么模型？ → model（简单 haiku，复杂 sonnet）

Skill正文
#

Skill.md的正文本质上还是会通过Promot一起提交给大模型，所以在Skill.md的正文内容没有说强制的规定需要怎么写，只需要表达出Skill的内容即可。在书写时我们可以应用一些技巧，让我们的Skill更加高效。

技巧1：通过 ARGUMENTS 给 Skill 传参

当你通过 /skill-name args 调用 Skill 时，args 会通过 $ARGUMENTS 注入到 Skill 内容中。举例来说，当运行 /fix-issue 123 时，Claude 收到的内容是“Fix GitHub issue 123 following our coding standards…”。

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

当然如果有多个参数要传递，它也是支持的。举例来说，当运行/pr-create “Add auth” “JWT” 时，下面示例中$1 = “Add auth”, $2 = “JWT”。

---
description: Create a pull request
argument-hint: [title] [description]
disable-model-invocation: true
---

Title: $1
Description: $2

技巧2：用 ! command 动态上下文注入

! command 是 Skill 文件的预处理器——在文件内容发送给模型之前，先在 shell 中执行这些预设的命令，然后把它们的输出结果内联替换到 Prompt 中，再去执行新的命令。示例：

## Current Context (Auto-detected)

Current branch:
!`git branch --show-current`

Recent commits on this branch:
!`git log origin/main..HEAD --oneline 2>/dev/null || echo "No commits ahead of main"`

Files changed:
!`git diff --stat origin/main 2>/dev/null || git diff --stat HEAD~3`

在应用Skill会实际执行上文中 git branch、git log 等命令，再传递给大模型，传递给大模型的内容如下：

## Current Context (Auto-detected)

Current branch:
feature/auth

Recent commits on this branch:
a1b2c3d Add JWT middleware
d4e5f6g Add login endpoint
g7h8i9j Add user model

Files changed:
 src/auth/middleware.ts | 45 +++
 src/auth/login.ts     | 82 +++
 src/models/user.ts    | 34 +++
 3 files changed, 161 insertions(+)

Skill设计原则
#

原则1. 单一职责原则：一个命令做一件事

✅ /commit, /push, /review
❌ /git-all-in-one

原则2. 清晰命名原则：从命令名就能知道它做什么

✅ /test:unit, /deploy:staging, /pr-create
❌ /do-stuff, /cmd1, /x

原则3. 有意义的参数提示：让使用者了解如何传参

✅ argument-hint: [commit message]
✅ argument-hint: [source file] [target directory]
❌ argument-hint: [args]

原则4. 权限最小化原则：严格控制每个任务的权限边界

✅ 精确授权——只允许 git 的特定子命令
allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*)

❌ 过于宽泛——等于授权所有 shell 命令
allowed-tools: Bash(*)

如何触发Skill
#

前面说了如何写Skill，现在来说下如何触发Skill。在 Claude Code 中，Skills 默认情况下支持两种触发方式：

用户显示触发：用户手动输入/skill-name，例如：/review、 /deploy
模型自动触发：Claude读取description，语义匹配后自动加载，例如：用户说“帮我审核这段代码”，Claude激活某个code-review Skill

这是 Skills 最重要的设计特性——同一个 Skill 既可以作为斜杠命令使用，也可以让 Claude 自动判断何时需要。

为什么要这样设计？用户有时知道自己要什么（/review），有时只是描述需求（“帮我看看代码“）。Skills 的双向触发机制让两种场景都能被满足，同时保持能力定义的统一。和 SubAgent 类似，Skills 的触发机制靠 LLM 语义推理，而非精确匹配。Claude 读取所有 Skills 的 description（再次强调description的重要性！！！），通过语义理解判断当前对话是否匹配某个 Skill。

当用户发送消息时，Claude 的处理流程如下图所示：

这里可以看出，每次提问Claude都会扫描所有Skill的description，再由模型来判断是否需要使用这个Skill，如果有需要，再去加载对应的Skill.md，这样就无需每次都把Skill的所有内容都丢给模型，这样即节省了token，又能让模型更加专注。前面说过一个Skill除了Skill.md外，还可以包含很多其他文件，这些文件也是按需加载而非一次性加载的。这种渐进式披露方式是Skill的核心机制。

Skill渐进式披露机制
#

前面我们不断地强调description的重要性，因为它是渐进式披露机制的重要载体，只有命中了description，Claude才会去加载Skill的正文内容，才会真正用到这个Skill。此外，我们还提到了一个Skill除了包含Skill.md外，还可以包含其他辅助文件，例如模版文件、引用文件、数据文件、脚本代码等，同样地，这些文件也不会一次性加载，也是等需要用到某个文件时，Claude才会去读取并把他们当作Promot的一部分。

渐进式披露的哲学
#

让我们用图书馆来类比渐进式披露的设计哲学。走进一个图书馆找资料时，你不会一次把所有书都读一遍。你是先看目录找到相关分类，再选一本具体的书，最后翻到需要的章节深入阅读。信息是逐层展开的，而不是一次性全部载入大脑。

Skill 的渐进式披露设计也是一样：第一层只扫描 description 作为“目录”，第二层在触发时加载 SKILL.md 主文件作为“章节”，第三层再按需加载被引用的具体文件作为“附录”。结构化分层替代信息堆叠，让系统在规模变大时依然高效、可控。

例如一个复杂的财务分析Skill，当通过Skill.md的description命中这个Skill后，会通过阅读Skill.md里的内容，来指定读取某个参考文件、模版文件、脚本文件。

.claude/skills/financial-analyzing/    # 标准 Skill 目录
├── SKILL.md                           # 主文件（总是加载）
├── reference/                         # 参考资料
│   ├── revenue.md                    # 收入分析公式
│   ├── costs.md                      # 成本分析公式
│   └── profitability.md              # 盈利分析公式
├── templates/                         # 报告模板
│   ├── quarterly_report.md
│   └── annual_report.md
├── data/                              # 数据文件
│   └── industry_benchmarks.json
└── scripts/                           # 分析脚本
    ├── calculate_ratios.py
    └── generate_report.sh

再来看看主文件SKILL.md是如何让大模型读取具体的辅助文件的

---
name: financial-analyzing
description: Analyze financial data, calculate financial ratios, and generate analysis reports. Use when the user asks about revenue, costs, profits, margins, ROI, financial metrics, or needs financial analysis of a company or project.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(python:*)
---

# Financial Analysis Skill

You are a financial analyst. Help users analyze financial data, calculate key metrics, and generate insightful reports.

## Quick Reference

| Analysis Type | When to Use | Reference |
|--------------|-------------|-----------|
| Revenue Analysis | 收入、营收、销售额相关 | `reference/revenue.md` |
| Cost Analysis | 成本、费用、支出相关 | `reference/costs.md` |
| Profitability | 利润、毛利率、净利率相关 | `reference/profitability.md` |

## Analysis Process

### Step 1: Understand the Question
- What financial aspect is the user asking about?
- What data do they have available?
- What format do they need the answer in?

### Step 2: Gather Data
- Request necessary financial data from user
- Or read from provided files/sources

### Step 3: Calculate Metrics
For specific formulas and calculations:
- Revenue metrics → see `reference/revenue.md`
- Cost metrics → see `reference/costs.md`
- Profitability metrics → see `reference/profitability.md`

To run calculations programmatically:
```bash
python scripts/calculate_ratios.py <data_file>

### Step 4: Generate Report
Use the template in `templates/analysis_report.md` for structured output.

## Output Guidelines

1. Always show your calculations
2. Explain what each metric means
3. Provide context (industry benchmarks when available)
4. Give actionable recommendations

## Important Notes

- Never make up financial data
- Ask for clarification if data is incomplete
- Flag any unusual numbers that might be errors

仔细观察上面的 SKILL.md 设计，你会发现它本质上是一个路由器——根据用户请求的类型，将 Claude 导向不同的资源文件：

用户请求 → SKILL.md（路由判断） → 目标资源
                │
                ├─ "收入相关" → reference/revenue.md
                ├─ "成本相关" → reference/costs.md
                ├─ "利润相关" → reference/profitability.md
                ├─ "要报告"   → templates/analysis_report.md
                └─ "要计算"   → scripts/calculate_ratios.py

这个路由的关键设计技巧是 Quick Reference 表格。它用最少的 token（3 行表格 ≈ 50 tokens）告诉 Claude 五个方向的路由。如果没有这个表格，Claude 需要阅读整个 SKILL.md 的 Step 3 才能知道“收入问题去找 revenue.md”——这就是信息密度的差异。写好路由表格的经验法则包括：

用“用户可能说的关键词”作为路由条件（而非“文件内容的技术名称”）
每个路由条目一行，不要超过 10 个条目（超过就需要分层）
高频路由放前面

此外主文件Skill.md应该控制在 500 行以内，文件组织则推荐使用按功能分类，例如：

.claude/skills/my-skill/
├── SKILL.md           # 入口 + 路由（< 500 行）
├── reference/         # 知识库（公式、规范、基准）
├── templates/         # 输出模板（报告、代码骨架）
├── examples/          # 示例集（输入输出样本）
├── scripts/           # 可执行脚本（计算、生成、验证）
└── data/              # 静态数据（JSON、CSV）

契约式引用
#

什么是契约式引用？简单来说就是SKILL.md 引用辅助文件时，不要只写一个路径——要写一个契约，让 Claude 知道什么时候该加载、加载后能得到什么：

❌ 弱引用（Claude 不知道何时该加载）
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

契约式引用三要素包括：

触发条件：什么情况下应该加载（“当用户问到 X 时”）
文件路径：去哪里找
内容预期：加载后能得到什么（“计算公式和行业基准”）

Skill的归类原则
#

面对一坨知识，怎么决定什么放 SKILL.md、什么放引用文件、什么放脚本？可以看下面的归类决策树：

这棵树背后真正体现的，是核心语义内联，确定逻辑外包，结构独立，数据延迟，示例分离等大原则。当你按照这个思路拆分 Skill，你构建的就不再是一份长文档，而是一套有层级的能力结构。这也是渐进式加载能够真正发挥作用的前提。

Skill的设计模式
#

在实际设计 Skill 时，有哪些经过验证的模式可以给我们一些场景应用启发？这里给出四种常见的设计模式，也可以说是典型应用场景吧。

模式1：模板驱动
#

模板驱动模式核心是用模板强约束输出结构，让结果稳定、可对比、可自动解析。适用于报告生成、文档输出等需要格式一致性的场景。它解决的是“输出不稳定”的问题，本质是把自然语言生成转化为结构化接口。

.claude/skills/report-generating/
├── SKILL.md              # 路由 + 流程
└── templates/
    ├── weekly_report.md   # 周报模板
    ├── incident.md        # 事故报告模板
    └── review.md          # 评审报告模板

SKILL.md 关键写法：

## Output Rules
- ALWAYS use the template from `templates/` that matches the request type
- Fill ALL placeholders — do not leave {placeholder} unfilled
- Do NOT add sections beyond what the template defines

模式2：脚本增强
#

脚本增强模式的核心是把计算、匹配、数据转换等确定性逻辑交给脚本执行，而不是让 Claude 推理完成。适用于公式计算、正则匹配、指标统计等场景。它解决的是“结果不稳定”的问题，本质是把概率型推理替换为确定性执行。

.claude/skills/data-analyzing/
├── SKILL.md              # 路由 + 流程
└── scripts/
    ├── parse_csv.py       # 数据解析
    ├── calculate.py       # 指标计算
    └── visualize.py       # 生成图表 HTML

如果你在 SKILL.md 里开始写公式，让 Claude 去计算或反复推理数值结果，那就应该停下来思考——这种确定性计算应当下沉到脚本中完成。Claude 负责判断和理解，脚本负责计算和执行。脚本不应依赖额外的外部安装环境（例如运行时需要再执行 pip install），优先使用标准库，若确有依赖必，须在说明文档中明确声明；脚本不应包含交互式输入，必须是一次性可执行、无人工干预的流程；同时也不要把所有逻辑都塞进脚本，只有确定性、可计算、可验证的逻辑才适合放入脚本，涉及判断、语义理解或策略决策的部分应保留给 Claude 处理。

模式3：知识分层
#

知识分层模式的核心是按使用频率组织知识，高频内联，中低频按需加载。适用于规则多、领域复杂的 Skill。它解决的是“上下文膨胀”的问题，本质是通过渐进加载控制认知复杂度。

.claude/skills/security-reviewing/
├── SKILL.md              # 核心检查清单（高频，~200 行）
├── QUICKREF.md           # 常见漏洞速查（中频）
├── OWASP_TOP10.md        # OWASP 详细标准（低频）
├── reference/
│   ├── xss.md           # XSS 防护详解（按需）
│   ├── sqli.md          # SQL 注入详解（按需）
│   └── auth.md          # 认证问题详解（按需）
└── examples/
    ├── good_auth.md      # 正确实现示例（按需）
    └── bad_patterns.md   # 反模式示例（按需）

分层策略：

总是加载（SKILL.md 内联）
← 80% 的请求只需要这些 
← 控制在 500 

行以内触发时加载（Quick Reference）
← 用户问到特定方向时加载 
← 契约式引用："When user asks about X → load Y"

按需加载（reference/ + examples/） 
← Claude 判断需要时才读取 
← 文件名要有描述性

模式4：工具隔离
#

工具隔离模式的核心是通过 allowed-tools 明确能力边界，限制 Skill 可以调用的工具。适用于需要安全控制或职责划分的场景。它解决的是“越权风险”的问题，本质是把安全约束前置为结构设计。当你需要确保 Skill 不会做“不该做的事”时——这是安全设计，不是功能设计。

# 审计类 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(npm test:*), Bash(pytest:*)]

四种模式不是互斥的——一个成熟的 Skill 通常组合使用多种模式。但理解每种模式的核心思想和适用边界，能帮你在设计时做出更好的取舍。

你的 Skill 需要……
│
├─ 标准化输出格式？ → 加 templates/（模板驱动）
├─ 确定性计算/匹配？ → 加 scripts/（脚本增强）
├─ 知识量 > 500 行？ → 拆分 reference/（知识分层）
└─ 安全边界控制？ → 配置 allowed-tools（工具隔离）

Skill的三层进化
#

回顾上述Skill的内容，我们实际上走了一条从简单到复杂的进化路径，这条路径映射到企业的知识管理成熟度，我们把他形容为三阶段进化，从SOP到组织智能。

阶段1：SOP阶段
#

阶段1是 SOP 阶段，一个 Skill 解决一个标准化任务。一个单一 SKILL.md，把流程写清楚，步骤可复现，行为可预测。就像企业里新写一份操作手册——照着做就行。

阶段2：专家系统阶段
#

在单一流程之上引入知识库、模板、脚本和权限控制，能够处理同一领域的各种复杂和边界情况。一个 Skill 通过渐进式披露组织丰富的领域知识，配合脚本和模板，成为完整的领域能力包。就像一个资深专家——不只有一份手册，还有工具箱、案例库、行业标准。

阶段3：组织智能阶段
#

多个 Skills 与 SubAgents 配合——分析子代理加载分析 Skill、审查子代理加载审查 Skill、测试子代理加载测试 Skill——形成流水线式的团队协作。加上 Hooks 的自动化质量控制和 Plugin 的打包分发，就构成了完整的“组织智能”。就像一家成熟的企业——每个部门有自己的 SOP，部门间有标准化交接流程，质检自动化运行。

这三级不是功能叠加，而是复杂度与抽象层级的进化。从 SOP 到专家系统，再到组织智能，是从可执行，到可扩展，再到可规模化的工程演进路径。

大多数项目在第2阶段就能满足了，不需要为了“高级”而过度设计——选择与问题复杂度匹配的级别。

Skill的权限体系与安全设计
#

在能力不断增强的同时，一个问题开始变得不可回避：当 Skill 变成组织级能力时，如何确保它“强大而不失控”？我们逐级来看。

在第一级 SOP 阶段，风险很小——它只是执行固定步骤。
在第二级专家系统阶段，Skill 已经可以调用多种工具、加载大量知识。
到了第三级组织智能阶段，多个 Skills 与 SubAgents 协作，自动触发、流水线运行，如果没有清晰的权限分层，系统很容易出现“能力越强，风险越大”的问题。

因此，Skill 的权限设计不是附加功能，而是组织智能能够落地的前提，权限设计本质上是在回答三个问题：

这个 Skill 能做什么？
这个 Skill 什么时候能被触发？
这个 Skill 在什么边界内运行？

设计一个生产级 Skill 时，建议按照 Skill 安全设计清单逐项检查。

检查项	问题	对策
工具权限	这个Skill需要写文件吗？	不需要就不给Write/Edit
自动触发	Calude自动触发有风险吗？	有副作用就 disable-model-invocation: true
Bash范围	需要执行什么命令？	用Bash(prefix:*)精确控制
上下文隔离	中间过程会污染对话吗？	重型任务用 context: frok
自动验证	输出需要格式检查吗？	加Skill升级Hooks

Skill的终极定义
#

Skills 是 Claude Code 架构中的知识层，它把人类组织几十年积累的知识管理经验（SOP、专家系统、组织学习）技术化映射到 AI Agent 架构中。

它不是被动的文档，而是有触发条件、有执行流程、有质量标准、有工具约束、有自动检查的可操作知识体系。

而它能出圈成为行业标准的原因是三个本质属性：声明式（纯 Markdown，无运行时依赖）、自包含（一个目录完整交付）、知识本位（价值在内容不在格式）。当格式趋近于纯知识时，采纳就变成了必然。

Skill的背景 #

Skill的类型 #

参考型 #

任务型 #

如何编写Skill #

Skill放在哪 #

Skill与Command的关系 #

Skill内容 #

Skill元数据 #

Skill正文 #

Skill设计原则 #

如何触发Skill #

Skill渐进式披露机制 #

渐进式披露的哲学 #

契约式引用 #

Skill的归类原则 #

Skill的设计模式 #

模式1：模板驱动 #

模式2：脚本增强 #

模式3：知识分层 #

模式4：工具隔离 #

Skill的三层进化 #

阶段1：SOP阶段 #

阶段2：专家系统阶段 #

阶段3：组织智能阶段 #

Skill的权限体系与安全设计 #

Skill的终极定义 #