对于喜欢偷懒的程序员，创建了一个命令来取代简单工作步骤，是再自然不过的事情，比如"检查一下 git 状态，然后提交代码，消息是 "fix login bug" 这种任务，用这样一个命令，直达目标。不需要每次都解释。
这就是任务型 Skill 的价值：把重复的对话模式，变成可复用的快捷方式。
这一讲是这样安排的：我们先了解任务型 Skill 的核心机制，随后梳理动态上下文注入技巧和 Skill 内的 Hooks 功能，之后学习任务型 Skill 的设计方法论和实战案例。
任务型 Skill 的核心机制
在上一讲中，我们曾经介绍过两大类型的任务，参考型和任务型。简单来说，任务型 Skill 就是设了 disable-model-invocation: true 的 Skill。
js
# 参考型------Claude 自动选择是否使用
name: api-conventions
description: API design patterns for this codebase. Use when writing or reviewing API endpoints.
# 任务型------必须用户手动触发
name: deploy
description: Deploy the application to production
disable-model-invocation: true
给 skill 传参
通过 ARGUMENTS 给 Skill 传参
当你通过 /skill-name args 调用 Skill 时，args 会通过 $ARGUMENTS 注入到 Skill 内容中。
举例来说，当运行 /fix-issue 123 时，Claude 收到的内容是"Fix GitHub issue 123 following our coding standards..."。
js
---
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注意，传参并不仅仅限于任务型 Skill，但是，需要明确传参的场景，对于任务型 Skill 自然是显得更加常见。
Skill 支持两种参数传递方式。
单参数------$ARGUMENTS 接收所有参数。
js
---
description: Quick git commit
argument-hint: [commit message]
disable-model-invocation: true
---
Create a git commit with message: $ARGUMENTS多参数 ------ 1，2 接收位置参数：
js
---
description: Create a pull request
argument-hint: [title] [description]
disable-model-invocation: true
---
Title: $1
Description: $2用法示例如下。
js
/commit fix login bug # $ARGUMENTS = "fix login bug"
/pr-create "Add auth" "JWT" # $1 = "Add auth", $2 = "JWT"可以用 ARGUMENTSN 或简写 N 访问特定位置的参数：
js
---
name: migrate-component
description: Migrate a component from one framework to another
---
Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.例如，/migrate-component SearchBar React Vue 中， 0被替换为SearchBar, 1 为 React, $2 为 Vue。
Claude Code 是非常灵活的，如果 Skill 中根本就没有定义 $ARGUMENTS，而你在调用 Skill 的时候又偏偏传递了参数进去。那也不怕，Claude Code 会自动在内容末尾追加 ARGUMENTS: <用户输入>，确保参数不会丢失。
! command 动态上下文注入
首先看一个场景：
当用户输入 /pr-create "Add auth" 时，模型收到的只是 Prompt 文本。它不知道：
- 当前在哪个分支
- 有哪些 commit 待合并
- 改了哪些文件
如果不预注入上下文，其实模型也会先花多轮工具调用去收集这些信息，任务虽然还是能完成，但浪费 token 和时间。
而 ! command 是 Skill 文件的预处理器------在文件内容发送给模型 之前，先在 shell 中执行这些预设的命令，然后把它们的输出结果内联替换到 Prompt 中，再去执行新的命令。执行流程如下：
下面的示例中，我们为 pr-create 命令设置 ! command ，让它能够动态接收上下文（上下文就是在技能中预设的 ! command 的输出）。
js
## 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`Claude 实际收到的 Prompt（替换后）：
js
## 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(+)这样，Claude 启动 /pr-create "Add auth" 时就拥有了完整上下文，可以直接生成 PR 标题和描述，无需额外再进行多一次工具调用。
我给上面的过程画了个图，方便大家更清晰地体会这个过程。
! command 可以与 $ARGUMENTS 组合，在动态注入时使用参数值。
js
---
description: Show git blame for a file
argument-hint: [file path]
disable-model-invocation: true
allowed-tools: Bash(git:*)
---
Analyze the git history for: $ARGUMENTS
File blame:
!`git blame $ARGUMENTS 2>/dev/null | head -30 || echo "File not found"`
Recent changes:
!`git log --oneline -5 -- $ARGUMENTS 2>/dev/null || echo "No history"`动态注入的工程价值和优势列表分析如下。
Skill 内的 Hooks
任务型 Skill 执行的是有"副作用"(side-effect）的操作------提交代码、部署应用、修改文件。这类操作需要自动化的安全网。
Hooks 配置很简单，只需要在 frontmatter 的 hooks 字段中定义：
js
---
description: Safe deployment command
disable-model-invocation: true
allowed-tools: Bash(git:*), Bash(npm:*), Bash(ssh:*)
hooks:
PreToolUse:
- matcher: Bash
hooks:
- type: "command"
command: echo "About to run: $TOOL_INPUT" >> /tmp/deploy.log
PostToolUse:
- matcher: Edit
hooks:
- type: "command"
command: npx prettier --write "$FILE_PATH"
---
Deploy the application to staging environment.Skill 中常用 Hook 模式如下。
Skill Hooks 与全局 Hooks 的区别如下。
任务型 Skill 设计方法论
设计一个任务型 Skill 时，我给你提供一个七步设计清单，引导你按顺序回答后面的问题。
js
1. 动作是什么？ → 命名（commit、deplo，y、review）
2. 谁能触发？ → disable-model-invocation: true
3. 需要什么权限？→ allowed-tools 精确到命令级
4. 启动时需要什么上下文？→ !`command` 预注入
5. 执行过程需要什么安全网？→ hooks
6. 输出量大不大？→ 大则 context: fork
7. 用什么模型？ → model（简单 haiku，复杂 sonnet）任务型 Skill 的几个重要设计原则如下：
-
单一职责原则：一个命令做一件事。
-
清晰命名原则：从命令名就能知道它做什么。
-
有意义的参数提示：让使用者了解如何传参。
js
✅ argument-hint: [commit message]
✅ argument-hint: [source file] [target directory]
❌ argument-hint: [args]- 权限最小化原则：严格控制每个任务的权限边界。
js
# ✅ 精确授权------只允许 git 的特定子命令
allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*)
# ❌ 过于宽泛------等于授权所有 shell 命令
allowed-tools: Bash(*)- 错误处理也非常重要，不可忽视。应该在说明中显式处理错误路径。
js
## Steps
1. Check if we're in a git repository
- If not, inform the user and stop
2. Check for uncommitted changes
- If none, inform the user that there's nothing to commit
3. Otherwise, proceed with the commit创建一个智能提交的skill
.claude/skills/committing/SKILL.md
js
---
description: Quick git commit with auto-generated or specified message
argument-hint: [optional: commit message]
disable-model-invocation: true
allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*), Bash(git diff:*)
model: haiku
---
Create a git commit.
If a message is provided: $ARGUMENTS
- Use that as the commit message
If no message is provided:
- Analyze the changes with `git diff --staged` (or `git diff` if nothing staged)
- Generate a concise, meaningful commit message
## Steps
1. Check `git status` to see current state
2. If nothing staged, run `git add .` to stage all changes
3. Review what will be committed with `git diff --staged`
4. Create commit:
- If `$ARGUMENTS` is provided, use it as the message
- Otherwise, generate a message based on the diff
5. Show the commit result
## Commit Message Format
- Start with type: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
- Be concise but descriptive (max 72 chars for first line)
- Example: `feat: add user authentication with JWT`
## Output
Show a brief confirmation:
✓ Committed: [commit message] [number] files changed使用方式如下：
js
# 自动生成 commit message
/commit
# 使用指定的 message
/commit fix: resolve login validation bug这个命令可以自动生成 commit message，也可以使用用户提供的说明。有参数用参数，没参数自动生成；内部会强制遵循 conventional commits 格式；使用 haiku 模型，响应快；而且只授权 git 相关命令。
如何创建一个复杂的skill
在真实场景中，专业能力往往很复杂，比如一个财务分析 Skill，它需要包含财务指标计算公式、不同行业的基准数据、各种报表模板、分析脚本以及案例示例。如果把这些全部塞进一个 SKILL.md，会有两个问题。
如果把这些全部塞进一个 SKILL.md，会有两个问题。
- Token 爆炸：每次激活都要加载几千 tokens。
- 信息噪声：用户问"收入增长率怎么算"，Claude 却要阅读关于成本分析、现金流、资产负债表的全部内容。
渐进式披露（Progressive Disclosure，也即是渐进式的加载啦）就是解决这个问题的架构模式。但渐进式披露的意义远不止节省 token。它是知识管理（Knowledge Management）在 AI 架构中的技术映射------如何让正确的知识在正确的时刻到达正确的执行者手中。
渐进式披露的设计哲学
让我们用图书馆来类比渐进式披露的设计哲学。走进一个图书馆找资料时，你不会一次把所有书都读一遍。你是先看目录找到相关分类，再选一本具体的书，最后翻到需要的章节深入阅读。信息是逐层展开的，而不是一次性全部载入大脑。
Skill 的渐进式披露设计也是一样：第一层只扫描 description 作为"目录"，第二层在触发时加载 SKILL.md 主文件作为"章节"，第三层再按需加载被引用的具体文件作为"附录"。结构化分层替代信息堆叠，让系统在规模变大时依然高效、可控。
认知经济学：上下文窗口是稀缺资源
在讨论 token 节省之前，让我们建立一个更深层的认知框架。
上下文窗口是 LLM 的"工作记忆"。 人类的工作记忆大约能同时处理 7±2 个信息块（Miller's Law）。LLM 的上下文窗口虽然大得多（200K tokens），但它也是有限的稀缺资源，而且有一个更严重的问题------注意力稀释效应。
Token 节省效果方面。让我们用数字说话。假设一个复杂的 Skill 是这样的：
不同场景下的 Token 消耗（大概估算哈）。
不难发现，大多数请求只需要部分资源，渐进式披露在这些场景下大幅节省 tokens。
财务分析 Skill：三层架构详解
我们今天要设计的这个财务分析 Skill，本质上是一个结构化的财务能力包：当用户提出与收入、成本、利润、增长率、毛利率、ROE/ROA 或整体财务表现相关的问题时，它会被激活，先在主文件中完成问题识别和分析路径判断，再按需加载对应的公式说明、行业基准数据或报告模板，必要时调用脚本进行确定性计算，最后输出结构清晰、口径一致的分析结果。
它的目标不是给投资建议，而是在明确数据前提下，提供可复现、可解释、可结构化的财务分析支持，用最少的上下文投入完成高质量的专业判断。
层级 1：目录页（Entry Point）
这是 Skills 系统扫描阶段读取的内容------只有 description。
js
---
name: financial-analyzing
description: Analyze financial data, calculate ratios, and generate reports. Use when the user asks about revenue, costs, profits, margins, financial metrics, or needs financial analysis.
---目录页的设计原则是，description 足够丰富，让 Claude 能准确判断相关性。但不要太长，因为所有 Skill 的 description 共享 15,000 字符的总预算。如果 Skill 数量多导致 description 被截断，可以通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量调整。
层级 2：章节（Main Content）
章节指的是 SKILL.md 的正文部分------激活后才加载。
js
# Financial Analysis Skill
## Quick Start
基础的财务分析流程...
## Available Analyses
### Revenue Analysis
For detailed formulas, see `reference/revenue.md`
### Cost Analysis
For detailed formulas, see `reference/costs.md`
### Profitability Analysis
For detailed formulas, see `reference/profitability.md`
## When to Load Additional Resources
- 需要具体公式 → 加载对应的 reference/*.md
- 需要行业基准 → 加载 data/benchmarks.json
- 需要报告模板 → 加载 templates/*.md这一部分的设计原则是主文件提供"路线图"，通过文件引用指向详细内容，然后 Claude 根据用户请求决定加载哪些具体内容。
层级 3：附录（On-Demand Resources）
只有当 SKILL.md 中引用了这些文件，Claude 才会去读取这一类文件。
js
.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这一部分内容的设计原则是文件名要有描述性（revenue.md 而非 ref1.md）------Claude 根据文件名判断是否需要加载。
所有辅助文件都在 Skill 自己的目录内，随 Skill 一起分发。相关内容放在一起，并按功能域组织子目录。例如脚本有自己独立存放的目录，Claude 可以执行它，但不需要去"理解"（这样也就节省了 Token）。
财务分析 Skill：项目设计细节
这个 Skill 标准部署结构如下：
js
your-project/.claude/skills/financial-analyzing/
├── SKILL.md # 主 Skill 文件
├── reference/
│ ├── revenue.md # 收入分析
│ ├── costs.md # 成本分析
│ └── profitability.md # 盈利分析
├── templates/
│ └── analysis_report.md # 分析报告模板
└── scripts/
└── calculate_ratios.py # 比率计算脚本主文件 SKILL.md 设计如下。
js
---
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 包括一个 Quick Reference 表格，让 Claude 快速定位需要哪个参考文件。使用相对路径指向资源，进行清晰的文件引用，并通过脚本调用说明告诉 Claude 如何使用计算脚本。同时只允许 Read、Grep、Glob 和特定的 Bash 命令。
仔细观察上面的 SKILL.md 设计，你会发现它本质上是一个路由器------根据用户请求的类型，将 Claude 导向不同的资源文件：
js
用户请求 → 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"------这就是信息密度的差异。
参考文件：reference/revenue.md
这是渐进式披露的层级 3 资源------只有当用户问到收入相关问题时，Claude 才会根据 SKILL.md 中 Quick Reference 表格的路由指引加载这个文件。它包含收入增长率、同比 / 环比、ARPU 等核心公式和异常信号判断标准。
报告模板：templates/analysis_report.md
模板文件是渐进式披露中的特殊资源------它不提供"知识"，而是提供"输出格式"。当用户要求"生成分析报告"时，Claude 加载这个模板来确保输出结构统一、专业。这就是企业知识管理中"标准化输出"的技术映射。
js
# Financial Analysis Report Template
## Executive Summary
[One paragraph summarizing key findings and recommendations]
## Company/Project Overview
- **Name**: [Entity name]
- **Period Analyzed**: [Date range]
- **Data Sources**: [Where data came from]
## Key Metrics
| Metric | Value | Industry Avg | Assessment |
|--------|-------|--------------|------------|
| Revenue Growth | X% | Y% | Above/Below |
| Gross Margin | X% | Y% | Above/Below |
| Net Margin | X% | Y% | Above/Below |
| ROI | X% | Y% | Above/Below |
## Detailed Analysis
### Revenue Analysis
[Findings about revenue trends, composition, growth]
### Cost Analysis
[Findings about cost structure, efficiency]
### Profitability Analysis
[Findings about margins, returns]
## Trend Analysis
[How metrics have changed over time]
## Recommendations
### Immediate Actions
1. [High priority recommendation]
2. [High priority recommendation]
### Medium-term Improvements
1. [Medium priority recommendation]
### Long-term Strategy
1. [Strategic recommendation]
## Risk Factors
- [Key risk 1]
- [Key risk 2]
## Appendix
[Supporting calculations, data tables, charts]计算脚本：scripts/calculate_ratios.py
脚本是 Skills 与 Tools 的桥梁------它把"知识"（公式）变成了"行动"（代码）。Claude 不需要理解计算逻辑，只需执行 python calculate_ratios.py data.json 即可获得准确结果。这比让 LLM 自己做数学运算更可靠、更省 token。
使用
场景 1：简单问题
用户：毛利率怎么计算？
Claude 加载过程：
-
扫描 Skills → 发现 financial-analyzing 匹配
-
加载 SKILL.md → 看到 "Profitability → see reference/profitability.md"
-
加载 reference/profitability.md → 找到毛利率公式
-
回答用户
Token 消耗：~100（扫描）+ 800（主文件）+ 600（profitability.md 部分）= ~1500 tokens
其他文件（revenue.md、costs.md、templates、scripts）完全没有加载。
如图所示，此时，Claude 只读取了 .claude/skills/financial-analyzing/reference/profitability.md 这一个文件的 83 行。
场景 2：完整分析
用户：帮我分析 data 目录中的财务数据，生成一份完整的分析报告。
Claude 加载过程：
-
扫描 Skills，发现 financial-analyzing 匹配
-
加载 SKILL.md
-
分析任务需要，加载所有 reference/*.md
-
需要报告格式，加载 templates/analysis_report.md
-
需要计算 ，执行 scripts/calculate_ratios.py
Token 消耗：全部资源都用到了。
渐进式的设计模式与最佳实践
1. 文件组织模式
js
.claude/skills/my-skill/
├── SKILL.md # 入口 + 路由（< 500 行）
├── reference/ # 知识库（公式、规范、基准）
├── templates/ # 输出模板（报告、代码骨架）
├── examples/ # 示例集（输入输出样本）
├── scripts/ # 可执行脚本（计算、生成、验证）
└── data/ # 静态数据（JSON、CSV）2. 主文件设计原则
主文件应该控制在 500 行以内（官方建议：Keep SKILL.md under 500 lines. Move detailed reference material to separate files.）。然后应该提供路线图，用 Quick Reference 表格做个快速路由，而非让 Claude 逐行扫描。
什么内容放主文件，什么内容放引用文件？
答案是高频内容内联，低频内容外链。最常用的信息直接放在主文件（80/20 法则------80% 请求只需 20% 内容）；偶尔用到的详细信息放在引用文件，用契约式引用。
到底啥是契约式引用？
SKILL.md 引用辅助文件时，不要只写一个路径------要写一个契约，让 Claude 知道什么时候该加载、加载后能得到什么：
js
# ❌ 弱引用（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引用文件命名也有所讲究，要清晰，切忌模糊，重复。
js
# 好的命名
reference/revenue.md # 清晰表明内容
reference/profitability.md # 清晰表明内容
templates/quarterly_report.md # 清晰表明用途
# 差的命名
reference/ref1.md # 不知道是什么
docs/misc.md # 太模糊
file.md # 毫无信息3. 脚本适合封装复杂但确定性的逻辑
脚本的好处是 Claude Code 可以直接执行它，而不需要"理解""每一行代码，因此可以减少 Token 消耗（不需要把逻辑放在 prompt 中），便于测试和维护（独立的代码文件）。
js
# 适合脚本
- 财务比率计算（公式固定）
- 数据格式转换（规则明确）
- 文件批量处理（重复性高）
# 不适合脚本
- 开放性分析（需要判断）
- 创意性任务（需要灵活性）
- 交互式决策（需要反馈）SKILL.md 只需要告诉 Claude 运行脚本：
js
---
name: codebase-visualizer
description: Generate an interactive tree visualization of your codebase. Use when exploring a new repo or understanding project structure.
allowed-tools: Bash(python *)
---
Run the visualization script from your project root:
\```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
\```
This creates `codebase-map.html` and opens it in your default browser.没有脚本时，Claude 需要自己组合多个 Tool 调用来完成任务：
js
手动编排（没有脚本）：
1. Read(data.json) → 获取数据
2. Claude 内部计算 → 消耗推理 token
3. 可能出错 → 需要多轮修正有脚本时，Claude 只需一次 Tool 调用：
js
脚本编排（有脚本）：
1. Bash(python calculate.py data.json) → 直接获得结果脚本是"预编译"的知识------它把人类专家的领域逻辑固化为代码，让 Claude 不需要在运行时"重新发明轮子"。
当你按照这个思路拆分 Skill，你构建的就不再是一份长文档，而是一套有层级的能力结构。这也是渐进式加载能够真正发挥作用的前提。
