跳到主内容
✍️ 公众号文章
AI 教师
学生
经/管/金融人

第 7 章 Skills 基础

系统讲解 Claude Code 中 Agent Skill 的概念、SKILL.md 结构与 YAML 字段、三阶段触发与渐进式披露机制,区分文档资产型、流程自动化型与 MCP 增强型三类 Skill,给出设计原则、常见误区,并以财报摘要和宏观指标速览两个经济金融案例演示创建与使用。

李学恒18 分钟阅读#claude-code#skills#skill-md#progressive-disclosure#prompt-engineering

本文节选《经济金融 AI 智能体设计:从理论到实践》第二部分。这本书正在编写中,面向经管学生、金融从业者和对 AI 智能体感兴趣的读者,教你用 Claude Code / Opencode / Codex 等工具来设计和管理 AI 智能体系统。全书覆盖从环境搭建、到多智能体基础、再到多个大型业界应用案例和科研应用案例的完整路径。

第 7 章总览图

学习目标

  1. 理解 Skill 的定义、价值和三种分类
  2. 掌握 SKILL.md 的结构、YAML frontmatter 字段规范和 description 写作方法
  3. 分析 渐进式披露的三层机制,判断触发问题的成因
  4. 辨析 Skill 与重复 prompt、命令、脚本、MCP 的职责差异
  5. 应用 设计原则评估一个任务是否适合封装为 Skill

这一章回答:什么是 Agent Skill,一个最小 Skill 由什么构成,系统怎样发现并加载它,哪些任务适合先封装为 Skill。脚本编排、设计模式和测试迭代不在这里展开。

本章结构:先从重复提示的痛点引出 Skill 的价值,再拆解 SKILL.md 的结构与核心字段,然后讲系统怎样发现和加载 Skill 的触发与渐进式披露机制,接着按文档资产型、流程自动化型和 MCP 增强型梳理三类 Skill 的适用场景,之后划清 Skill 与重复 prompt、命令、脚本、MCP 的分工边界,最后收束设计原则与常见误区。

7.1 从重复提示到可复用 Skill

7.1 配图

当一项任务反复出现,问题就不再是会不会写 prompt,而是同一套做法能不能稳定复用。一次性任务用临时 prompt 足够;一旦进入重复协作,临时写法很快会暴露问题。

第一,要求容易漂移。今天你要求先提炼要点再列行动项,明天可能只写成帮我总结一下,后天又补上一句按会议纪要格式输出。同一任务,因为表达不同,结果不断波动。

第二,经验难以积累。一次次对话里,其实已经摸索出更好的顺序、更稳的格式、更清楚的边界,但这些经验分散在历史记录中,无法直接复用。

第三,协作难以统一。一个人熟悉自己的 prompt 习惯,不代表团队其他成员能复现同样结果。没有统一说明书,任务质量就依赖个人手感。

Skill 解决的正是这三个问题。它把这类任务该怎样做提前写清楚,把散落在会话里的经验收成可复用的工作规则。

智能体面对任务时,不再每次重新摸索,而是优先套用已经验证过的方法。

可以把它看成三步演化:

阶段临时 prompt重复 promptSkill
复用性一次性,用完即弃手动复制粘贴系统自动匹配加载
一致性每次表述不同,结果波动取决于是否记得上次怎么写规则固定,结果稳定
协作性仅限个人靠口头传递文件化,团队共享
维护成本无需维护散落各处,难以更新集中维护,版本可控

Skill:一组打包在文件夹中的指令,教会 Claude 如何处理特定任务或工作流。Skill 的核心文件是 SKILL.md,包含 YAML 元数据和 Markdown 格式的执行规则。Skill 不是更长的 prompt——它由系统自动匹配和加载,具备渐进式披露机制,支持跨会话复用。

本节只建立一个基本判断:当某类任务反复出现,而且总要重复解释做法时,就该考虑 Skill。

不过,并非所有 Skill 都长一个样。根据 Anthropic 官方指南,Skill 可以分为三类:文档资产型(Document & Asset Creation)产出文档和报告,不依赖外部工具;流程自动化型(Workflow Automation)编排多步流程并内置验证节点;MCP 增强型(MCP Enhancement)在工具接口之上叠加领域专业知识。这三类各有不同的适用场景和设计要点。

7.2 SKILL.md 的结构与核心字段

7.2 配图

理解 Skill,不必先被复杂目录吓住。一个最小可用的 Skill,核心只需要一个文件:SKILL.md

这个文件承担两件事。第一,告诉系统它是什么、什么时候该调用;第二,告诉智能体调用之后该按什么步骤工作。前者负责被发现,后者负责被执行。

两层结构

从教学角度看,Skill 可以分成两层。

层级包含内容是否必需作用
最小层SKILL.md(含 YAML frontmatter + 正文步骤)必需定义触发条件和执行规则
增强层scripts/references/assets/可选提供脚本、参考文档、模板资源

只要 SKILL.md 写得清楚,一个 Skill 就已经成立。增强层可以让 Skill 更完整,但不是理解概念的前提。

词条:SKILL.md

  • 定义:Skill 的核心说明文件,由 YAML frontmatter 和 Markdown 正文两部分组成。
  • 常见误解:没有脚本就不算完整 Skill。
  • 命名规则:必须严格写成 SKILL.md(大小写敏感),不接受 skill.mdSKILL.MD 等变体。

文件夹结构

一个完整的 Skill 文件夹结构如下:

financial-report-summary/
├── SKILL.md                  # 必需 - 核心说明文件
├── scripts/                  # 可选 - 可执行脚本
│   └── validate_format.py
├── references/               # 可选 - 参考文档
│   └── report-style-guide.md
└── assets/                   # 可选 - 模板和资源
    └── summary-template.md

文件夹命名有严格规则:

  • 使用 kebab-case(短横线分隔小写字母):financial-report-summary
  • 禁止空格:Financial Report Summary
  • 禁止下划线:financial_report_summary
  • 禁止大写字母:FinancialReportSummary
  • 禁止包含 claude 或 anthropic(保留词)

存储位置

Skill 有两个存储层级:

层级路径作用域
个人级~/.claude/skills/所有项目共享
项目级项目目录/.claude/skills/仅当前项目可用

个人级 Skill 适合通用工具,如会议纪要整理、日报生成。项目级 Skill 适合特定业务,如某基金公司的研报摘要模板。

YAML Frontmatter 字段规范

SKILL.md 的开头是 YAML frontmatter,用 --- 包裹。这是系统识别 Skill 的入口。

字段是否必填说明
name必填kebab-case 格式,应与文件夹名一致
description必填说明做什么、何时使用,不超过 1024 字符
license可选开源协议,如 MIT、Apache-2.0
compatibility可选环境要求,如依赖的系统包或网络条件,1-500 字符
metadata可选自定义键值对,如 author、version、mcp-server
allowed-tools可选限定 Skill 可使用的工具,如 "Bash(python:*) Read Glob"

安全限制

Frontmatter 中禁止使用 XML 尖括号(<>),因为 frontmatter 会出现在系统提示中,尖括号可能被利用来注入指令。

description 写作方法

description 是 Skill 最关键的字段。它决定系统能否准确匹配当前任务。

写作公式:做什么 + 何时使用 + 关键能力

好的 description 示例:

# 具体且包含触发短语
description: >
  整理会议记录并生成结构化纪要。当用户要求总结会议、
  提炼行动项、生成会议纪要时使用。支持中英文会议内容,
  输出包含议题、结论、行动项和待确认事项。
# 明确触发场景和能力边界
description: >
  分析上市公司季度财报数据并生成对比摘要。当用户提到
  季报分析、财务指标对比、盈利能力评估时使用。覆盖
  营收、利润、现金流三大类指标。

不好的 description 示例:

# 太模糊,无法区分用途
description: 帮助处理文档。

# 缺少触发场景
description: 生成高质量多页面结构化文档系统。

# 过于技术化,没有用户视角
description: 实现层级关系实体模型的序列化与反序列化。

最小示例

一个教材式的最小 Skill:

---
name: meeting-summary
description: >
  整理会议记录并生成结构化纪要。当用户要求总结会议、
  提炼行动项、生成会议纪要时使用。
# 会议纪要整理

## 执行步骤

### 第 1 步:识别会议信息
确认会议主题、参与人和时间。

### 第 2 步:提炼核心内容
从原始记录中提取关键结论、分歧点和待办事项。

### 第 3 步:结构化输出
按以下格式输出纪要:

- 会议主题
- 关键结论
- 行动项(含负责人和截止日期)
- 待确认问题

带完整 Frontmatter 的经济金融示例

---
name: quarterly-earnings-summary
description: >
  分析上市公司季度财报并生成结构化摘要。当用户提到
  季报分析、财务指标对比、盈利能力评估、季度业绩
  解读时使用。覆盖营收、利润率、现金流三大类指标。
license: MIT
compatibility: 需要访问本地文件系统读取财报 PDF 或 CSV
metadata:
  author: econ-finance-team
  version: 1.0.0
  category: financial-analysis
# 季度财报摘要生成

## 执行步骤

### 第 1 步:获取财报数据
读取用户提供的财报文件,确认报告期和公司名称。

### 第 2 步:计算核心指标
- 营收增长率(同比 / 环比)
- 毛利率、净利率变动
- 经营性现金流与净利润比值

### 第 3 步:生成对比分析
将本期数据与上期及去年同期对比,标注显著变动项。

### 第 4 步:输出结构化摘要
按固定格式输出:公司概况、核心指标表、重大变动说明、风险提示。

Skill 的质量不取决于文件夹有多丰富,而取决于规则是否稳定。 有些 Skill 目录很复杂,但触发条件模糊、正文泛泛而谈,实际并不好用。反过来,一个只有 SKILL.md 的 Skill,只要触发明确、步骤清楚,也能稳定发挥作用。

7.3 触发机制与渐进式披露

7.3 配图

知道 Skill 长什么样还不够,接下来要问的是:系统怎么知道什么时候该用它?

三阶段触发流程

在 Claude 的实现中,Skill 的加载分为三个阶段:

阶段动作读取内容上下文开销
发现扫描可用 Skillnamedescription极小(约 100 tokens / Skill)
匹配判断与当前任务的相关性元数据对比
加载读取正文与附加资源SKILL.md 正文、scripts/、references/按需增长

系统启动时,会把所有可用 Skill 的 frontmatter 加载到上下文中。每个 Skill 的 frontmatter 大约占 100 个 tokens。当用户提出请求,系统根据 name 和 description 判断哪些 Skill 与当前任务相关,只有判断相关的 Skill 才会被进一步读取正文。

渐进式披露的三层模型

这个机制的核心原则是渐进式披露(Progressive Disclosure)。它不是一次性把所有内容塞进上下文,而是分层按需展开。

词条:渐进式披露(Progressive Disclosure)

  • 定义:Skill 采用的三层信息加载策略。先暴露少量元数据,确认相关后再读取正文,必要时再访问附加文件。
  • 设计目标:在保持专业能力的同时,最小化 token 消耗。

三层模型的具体分工:

层级内容加载时机典型大小
第一层YAML frontmatter(name + description)始终加载到系统提示中~100 tokens
第二层SKILL.md 正文(步骤、示例、错误处理)系统判断相关时加载数百至数千 tokens
第三层链接文件(scripts/、references/、assets/)执行过程中按需读取视文件大小而定

这意味着,如果你安装了 20 个 Skill,系统并不会把 20 份完整说明都塞进上下文。它只加载 20 份 frontmatter(约 2000 tokens),然后根据当前任务选择性地展开 1 - 2 个 Skill 的正文。

description 决定触发质量

渐进式披露解释了一个关键事实:description 的质量直接决定触发是否准确。

在正文被读取之前,系统只能依靠 name 和 description 做判断。如果 description 写得很空,例如只写"一个有用的分析 Skill",系统就无法区分它适用于财报分析、舆情分析还是政策分析。描述越模糊,触发越不稳定。

调试技巧

如果不确定 Skill 的触发效果,可以直接问智能体:

你什么时候会使用 quarterly-earnings-summary 这个 Skill?

智能体会根据 description 回答它的理解。如果回答与你的预期不符,说明 description 需要修改。

触发不良的两种信号

触发问题通常表现为两种:

触发不足——Skill 在该用的时候没有被加载:

  • 用户明确提到相关任务,但 Skill 不响应
  • 用户需要手动启用 Skill
  • 典型原因:description 太模糊,缺少用户实际会说的短语

触发过度——Skill 在不该用的时候被加载:

  • 无关任务也触发了该 Skill
  • 用户主动禁用 Skill
  • 典型原因:description 太宽泛,没有界定适用边界

触发不足 vs 触发过度的应对

问题表现应对方法
触发不足相关任务不触发在 description 中增加具体的触发短语和关键词
触发过度无关任务也触发在 description 中添加否定条件,收窄适用范围

否定条件的写法示例:

description: >
  分析 CSV 格式的财务数据,执行统计建模和回归分析。
  当用户要求数据分析、财务建模、回归检验时使用。
  不用于简单的数据可视化(请使用 data-viz Skill)。

编写 Skill 时有一个实用原则:把最关键的触发信息写在 description 中,把详细执行步骤留给正文。 先让系统准确判断该不该用,再让正文回答用了以后怎么做。

7.4 三类 Skill 与适用场景

7.4 配图

Skill 并非千篇一律。根据 Anthropic 官方指南,Skill 可以按用途分为三类:文档资产型、流程自动化型和 MCP 增强型。三类的核心区别在于:是否需要外部工具,是否包含多步流程,以及领域知识在其中扮演什么角色。

文档资产型(Document & Asset Creation)

文档资产型 Skill 的目标是产出一致、高质量的文档或资产。它不依赖外部工具,完全利用 Claude 的内置能力完成工作。

典型特征

  • 嵌入格式规范和风格要求
  • 提供模板结构确保输出一致
  • 正文中包含质量检查清单
  • 无需 MCP 或外部 API

经济金融场景:会议纪要整理、研报摘要模板、政策简报生成、投资备忘录起草。

---
name: policy-briefing
description: >
  生成结构化政策简报。当用户要求撰写政策分析、
  政策解读、监管动态简报时使用。输出包含政策
  背景、核心条款、影响评估和应对建议四部分。
# 政策简报生成

## 执行步骤

### 第 1 步:确认政策信息
- 政策名称、发布机构、生效日期
- 适用行业和主体范围

### 第 2 步:提炼核心条款
- 列出 3-5 条关键条款
- 标注与现行规定的差异

### 第 3 步:评估影响
- 对行业格局的短期和中期影响
- 对主要市场参与者的影响

### 第 4 步:结构化输出
按固定格式输出简报:
- 一句话摘要
- 政策背景(不超过 200 字)
- 核心条款表
- 影响评估
- 应对建议

流程自动化型(Workflow Automation)

流程自动化型 Skill 编排多步流程,并在关键节点设置验证。它强调步骤顺序、依赖关系和质量门禁。

典型特征

  • 明确的步骤顺序和依赖关系
  • 每个阶段有验证条件
  • 内置审查和改进建议
  • 可包含迭代精修循环

经济金融场景:数据收集核对清单、季度财报分析流水线、尽职调查流程、合规检查清单。

---
name: due-diligence-checklist
description: >
  执行投资项目尽职调查流程。当用户提到尽职调查、
  DD checklist、投资前审查、标的公司调研时使用。
  按财务、法律、业务三个维度逐项核对。
# 投资尽职调查

## 执行步骤

### 第 1 步:收集基础资料
确认标的公司名称、行业、融资轮次。
读取用户提供的资料文件。

### 第 2 步:财务维度核查
- [ ] 近三年营收和利润趋势
- [ ] 现金流是否覆盖运营支出
- [ ] 应收账款周转率
- [ ] 重大关联交易

### 第 3 步:法律维度核查
- [ ] 股权结构是否清晰
- [ ] 是否存在未决诉讼
- [ ] 知识产权归属

### 第 4 步:业务维度核查
- [ ] 核心竞争力和护城河
- [ ] 客户集中度
- [ ] 行业监管风险

### 第 5 步:生成调查报告
汇总各维度结果,标注风险项和待补充事项。
输出结构化报告和待办清单。

MCP 增强型(MCP Enhancement)

MCP 增强型 Skill 在工具接口之上叠加领域专业知识。MCP 提供数据访问和工具调用能力,Skill 提供使用这些工具的最佳实践和工作流指引。

典型特征

  • 协调多个 MCP 工具调用的顺序
  • 嵌入领域专业知识和最佳实践
  • 提供用户原本需要自行摸索的上下文
  • 包含工具调用错误处理

经济金融场景:股票数据查询 + 合规检查、数据库查询 + 分析最佳实践、多平台研报聚合。

---
name: stock-compliance-check
description: >
  查询股票数据并执行合规检查。当用户要求查询
  持仓数据、检查交易合规性、生成合规报告时使用。
  需要 market-data MCP 服务。
allowed-tools: "Read Bash(python:*)"
metadata:
  mcp-server: market-data
# 股票数据合规检查

## 执行步骤

### 第 1 步:获取交易数据
通过 market-data MCP 查询指定股票的持仓和交易记录。

### 第 2 步:应用合规规则
- 检查单只股票持仓是否超过基金净值 10%
- 检查是否存在禁止期内的交易
- 检查关联方交易是否已报备

### 第 3 步:风险评估
根据检查结果评定合规等级:
- 合规:所有检查通过
- 待关注:存在接近阈值的项目
- 违规:存在超限或未报备项目

### 第 4 步:生成审计留痕
输出合规检查报告,包含检查时间、检查项、结果和建议。

如何选择 Skill 类型

面对一个具体任务,可以用三个问题快速判断它属于哪一类:

判断问题
是否需要调用外部工具或 API?→ 考虑 MCP 增强型→ 排除 MCP 增强型
是否包含多步流程且步骤间有依赖?→ 考虑流程自动化型→ 排除流程自动化型
核心价值是否在于输出格式和领域知识?→ 考虑文档资产型→ 排除文档资产型

实践建议

初学者建议从文档资产型 Skill 起步。它不依赖外部工具,结构简单,能快速验证 Skill 的触发和执行效果。熟悉基本机制后,再尝试流程自动化型和 MCP 增强型。

三类之间并非互斥。一个 Skill 可能同时具备多类特征。比如一个研报生成 Skill,既需要从 MCP 获取数据(MCP 增强型),又需要按固定流程处理(流程自动化型),最终输出标准化文档(文档资产型)。分类的目的是帮助设计时明确重心,而不是划定不可逾越的边界。

7.5 设计原则与常见误区

7.5 配图

并不是所有常用任务都值得做成 Skill。适合封装为 Skill 的任务,通常同时满足三个条件:

  1. 触发场景稳定——能用清晰的短语描述何时使用
  2. 处理步骤可复用——流程相对固定,不需要每次重新设计
  3. 输出标准明确——产出结果有清楚的格式或质量要求

满足这三个条件,Skill 才能真正减少重复劳动。不满足,则可能把混乱固化下来。

适合与不适合的对照

适合做成 Skill不适合做成 Skill
会议纪要整理(高频、结构稳定)头脑风暴新商业模式(探索性强)
固定格式研报摘要(输出标准明确)处理一次性临时材料(不会重复)
季度财报分析流程(步骤可复用)所有写作都交给一个 Skill(边界过宽)
合规检查清单(流程固定)开放式研究讨论(流程不稳定)

六条设计原则

原则含义反例
单一职责一个 Skill 只做一类事把摘要、改写、校对塞进同一个 Skill
描述可判别description 能让系统准确匹配写成一个有用的写作 Skill
正文可执行步骤足够具体,智能体能照做正文只写请认真完成任务
边界可说明清楚什么不属于这个 Skill 的范围把所有相关功能都往里塞
可组合多个 Skill 并存时不互相冲突两个 Skill 争抢同一类任务的触发权
可移植跨平台使用时行为一致依赖特定环境变量而不在 compatibility 中声明

前四条是基础原则,确保单个 Skill 能独立工作。后两条是协作原则,确保 Skill 在多 Skill 环境和跨平台场景下依然可靠。

可组合意味着你的 Skill 不应假设自己是唯一被加载的能力。Claude 可以同时加载多个 Skill,每个 Skill 应当在自己的职责范围内工作,不与其他 Skill 产生歧义。

可移植意味着同一个 Skill 应当在 Claude.ai、Claude Code 和 API 中产生一致的行为。如果 Skill 依赖特定环境(如某个系统包或网络条件),应在 frontmatter 的 compatibility 字段中明确声明。

常见误区

误区速查

误区问题正确做法
Skill 越大越好边界模糊,触发失真保持单一职责,一个 Skill 只做一类事
没有脚本就不算 Skill混淆了最小层和增强层只有 SKILL.md 也能成立
description 越宽泛越好系统无法准确匹配写清具体的触发场景和否定条件
先收集 Skill 再学原理缺乏判断力,无法评估质量先掌握设计原则,再决定复用

核心判断

一个任务是否适合封装为 Skill,取决于三个条件:触发场景是否稳定,处理步骤是否可复用,输出标准是否明确。如果三个条件都满足,从最小结构(只有 SKILL.md)起步,验证触发和执行效果后再逐步增强。

最后回到本章的边界。本章讨论的 Skill 都是基础层面的:一个 SKILL.md,一套触发和执行规则,最多配合少量辅助文件。当 Skill 开始连接脚本、编排多工具调用、嵌入复杂验证逻辑时,它就从说明书进一步发展为可执行工作流。

7.6 案例一:财报摘要 Skill

场景如下:你经常需要从上市公司季度财报中提取关键指标,生成标准化摘要。每次都手动写提示词,要反复交代输出格式、指标范围和约束条件。于是你决定创建一个 Skill,把这套流程固化下来。

A. 项目目录

financial-analysis/
├── .claude/
│   └── skills/
│       └── earnings-summary/
│           └── SKILL.md          # 财报摘要 Skill
├── data/
│   ├── 600519_2025Q4.pdf         # 贵州茅台财报
│   └── 002594_2025Q4.pdf         # 比亚迪财报
├── output/                       # Skill 产出目录
└── CLAUDE.md

Skill 放在项目级路径 .claude/skills/ 下,仅当前项目可用。data/ 存放原始财报,output/ 接收产出文件。

B. SKILL.md 配置

这是 earnings-summary 的完整 SKILL.md:

---
name: earnings-summary
description: >
  从上市公司季度财报 PDF 中提取核心财务指标,生成标准化摘要。
  当用户要求财报摘要、季报分析、财务指标提取时使用。
  覆盖营收、利润、现金流等核心指标,输出结构化摘要文件。
# 季度财报摘要

## 执行步骤

### 第 1 步:读取财报文件
读取用户指定的财报 PDF,确认公司名称、股票代码和报告期。

### 第 2 步:提取核心指标
从财报中提取以下数据:
- 营业收入
- 归属净利润
- 毛利率、净利率
- 研发费用
- 经营性现金流净额

### 第 3 步:计算变动幅度
如果财报中包含上期数据,计算同比和环比变化率。

### 第 4 步:生成摘要文件
写入 output/ 目录,文件名格式:{股票代码}_Q{季度}_摘要.md

## 输出格式

摘要包含三部分:
- 公司基本信息(名称、代码、报告期)
- 核心指标表格(指标名称、本期值、同比变化)
- 经营总结(不超过 200 字,概括本季度亮点和风险)

## 约束

- 所有数据必须来自财报文件,不可编造或补充外部数据
- 指标缺失时在表格中标注"未披露"
- 总结部分只陈述事实,不做投资建议

YAML frontmatter 中的 description 是触发匹配的核心依据。系统根据用户输入和 description 的语义相似度决定是否激活这个 Skill,所以关键词要覆盖用户可能的表述方式——"财报摘要"、"季报分析"、"财务指标提取"都指向同一个需求。正文部分把执行步骤、输出格式和约束条件一次写清,后续每次使用都不必重复交代。

C. 实际使用

Skill 创建完成后,在 Claude Code 中输入:

请帮我生成贵州茅台 2025Q4 的财报摘要。
财报文件在 data/600519_2025Q4.pdf。

用户只需说出意图和文件位置。系统匹配到 earnings-summary Skill 后,自动按 SKILL.md 中定义的步骤执行:读取 PDF、提取指标、计算变动、写入摘要文件。

如果要批量处理,只需换一个文件路径:

再帮我生成比亚迪 2025Q4 的财报摘要,文件是 data/002594_2025Q4.pdf。

同一个 Skill,不同的输入,产出格式始终一致。

这就是 Skill 的核心价值:把每次都要重复的详细提示词,固化为一次配置、反复使用的标准化能力。写一次 SKILL.md,省下所有后续的重复解释。

7.7 案例二:宏观经济指标速览 Skill

另一个常见场景:你需要定期跟踪宏观经济数据——GDP 增速、CPI、PMI、社融规模等。每次分析都要交代数据来源、指标口径、对比维度和输出格式。创建一个 Skill,把这些要求固化。

A. 项目目录

macro-tracker/
├── .claude/
│   └── skills/
│       └── macro-snapshot/
│           └── SKILL.md          # 宏观指标速览 Skill
├── data/
│   ├── nbs_monthly_202502.csv    # 国家统计局月度数据
│   └── pboc_monetary_202502.csv  # 央行货币金融数据
├── output/                       # Skill 产出目录
└── CLAUDE.md

data/ 存放从国家统计局和央行下载的月度数据文件。Skill 读取这些 CSV,产出标准化速览报告。

B. SKILL.md 配置

---
name: macro-snapshot
description: >
  从宏观经济数据文件中提取核心指标,生成月度经济速览。
  当用户要求宏观数据总结、经济指标速览、月度经济回顾时使用。
  覆盖产出、物价、就业、货币四大维度。
# 宏观经济指标速览

## 执行步骤

### 第 1 步:读取数据文件
读取用户指定的 CSV 数据文件,确认数据来源和统计期。

### 第 2 步:提取四大维度指标
从数据中提取以下核心指标:
- 产出:GDP 同比增速、工业增加值、固定资产投资增速
- 物价:CPI 同比、PPI 同比
- 就业:城镇调查失业率
- 货币:M2 同比增速、社会融资规模增量

### 第 3 步:标注趋势方向
与上月数据对比,用 ↑ ↓ → 标注每个指标的变动方向。

### 第 4 步:生成速览文件
写入 output/ 目录,文件名格式:macro_snapshot_{年月}.md

## 输出格式

速览报告包含三部分:
- 统计期与数据来源说明
- 四大维度指标表格(指标名称、当期值、上期值、趋势)
- 一段话总结(不超过 150 字,概括当月经济运行特征)

## 约束

- 所有数值必须来自数据文件,不可使用外部数据
- 数据缺失时标注"暂缺"
- 总结只描述趋势,不做政策预测

description 覆盖了"宏观数据总结"、"经济指标速览"、"月度经济回顾"三种表述,确保用户用不同说法都能匹配到这个 Skill。

C. 实际使用

在 Claude Code 中输入:

帮我生成 2025 年 2 月的宏观经济指标速览。
统计局数据在 data/nbs_monthly_202502.csv,
央行数据在 data/pboc_monetary_202502.csv。

系统匹配到 macro-snapshot Skill,按四个步骤执行:读取 CSV、提取四大维度指标、标注趋势、写入速览文件。产出格式每月一致,方便纵向比较。

本章小结

本章的主线是一个判断:当同类任务反复出现,而且做法趋于稳定时,就该把它从临时 prompt 升级为可复用的 Skill。

具体来说,本章解决了六个基础问题:

  1. 为什么需要 Skill(7.1):重复 prompt 带来要求漂移、经验散落、协作失准三个问题。Skill 把隐性经验变成显性规则,由系统自动匹配加载。
  2. SKILL.md 的结构与字段(7.2):一个 SKILL.md 就能成立。YAML frontmatter 中 name 和 description 是必填字段,description 按做什么 + 何时使用 + 关键能力的公式编写。文件夹使用 kebab-case 命名,存储分个人级和项目级。
  3. 触发与渐进式披露(7.3):系统采用三层模型——frontmatter 始终加载,正文按需展开,附加文件执行时读取。description 的质量直接决定触发准确性,触发问题分为触发不足和触发过度两类。
  4. 三类 Skill(7.4):文档资产型产出文档,不依赖外部工具;流程自动化型编排多步流程;MCP 增强型在工具接口上叠加领域知识。三类可组合,初学者建议从文档资产型起步。
  5. 设计原则与常见误区(7.5):适合封装为 Skill 的任务满足触发稳定、步骤可复用、输出标准明确三个条件。六条设计原则覆盖单一职责、描述可判别、正文可执行、边界可说明、可组合、可移植。
  6. 案例(7.6-7.7):用财报摘要和宏观指标速览两个经济金融场景,从头到尾跑一遍 Skill 的创建、配置与使用。

实践建议

  1. 遇到重复任务时,先用三个条件(触发稳定、步骤可复用、输出标准明确)判断是否适合封装。
  2. 从最小结构起步:先只写 SKILL.md,验证触发和执行效果后再考虑增强。
  3. description 是最关键的字段——按做什么 + 何时使用 + 关键能力的公式编写,包含用户实际会说的短语。
  4. 一个 Skill 只做一类事。当你想往里塞第二类职责时,拆成两个 Skill。
  5. 调试触发效果时,直接问智能体你什么时候会使用这个 Skill,根据回答调整 description。

本章及全书仍在持续写作和修订中,内容会不断演进。欢迎读者提出任何反馈和建议,帮助我们把这本书打磨得更好。

related