CHAPTER 02

Skill 为什么这么厉害

不是更长的 prompt，
而是按需展开的"渐进披露"。

P9 – P22 · 14 页 · 含「现场实战 A」手搓 sql-query-api

?

互动一分钟 · 带着问题听

什么是 Skill？

它和写一段更长的提示词，有什么不同？

很多人第一反应：Skill 不就是把 prompt 写长一点、写细一点？
如果只是这样，为什么 Anthropic 要专门给它一套结构、一套加载机制？

现场讨论 1–2 分钟下一页揭晓答案

P10 · 一句话定位

Skill 是给 AI 用的，不是给人用的

Skill 不是「提示词扩展」
是把一个场景的经验 / 流程 / 工具 / 输出契约沉淀成可复用资产

~~给人看的说明书~~　→　给 AI 用的能力包　·　服务对象是 AI

1固化「容易踩的坑」

把调用工具、跑业务时反复踩的坑写成规则 —— 让 AI 不再每次重新犯错。

2固化垂直知识与 SOP

把垂直领域的专业判断、标准操作流程沉淀下来，AI 按既定路径走。

3消除「业务转技术」的偏差

业务需求 → 技术脚本之间的指令偏差，靠 Skill 的明确契约抹平。

4两个视角看 Skill

一个是 Anthropic 的 Skill 标准，一个是「为 AI 设计」的 研究视角。

P11 · Skill 的结构

SKILL.md + 渐进披露三级加载

左边是三级加载机制，右边用 Anthropic 自带的 Excel（xlsx）Skill 实际展开看一眼 —— 为什么要这样分层。

▌ 机制：三级加载

L1

metadata

常驻上下文 · ~1500 token / 40 个 Skill

只有 name + description 一直在。AI 靠它判断「该不该用这个 Skill」。

▼ 命中后才载入

L2

SKILL.md

按需载入 · 完整操作说明

真的要操作 Excel 时，才把正文读进来 —— 流程、规则、注意事项。

▼ 需要时再取

L3

references / scripts

关联资源 · 脚本运行

脚本不进 context，由 Harness 执行，AI 只读它打印的 stdout。

▌ 实例：把 Excel Skill 目录展开

xlsx/ # Anthropic 自带的 Excel 技能

├─ SKILL.md ◀ L1 metadata（描述常驻）

└ 正文：怎么读写/格式化表格 ◀ L2

├─ references/ ◀ L3 按需读

├ formulas.md # 公式用法

└ formatting.md # 样式规范

└─ scripts/ ◀ L3 只跑不读

└ recalc.py # 公式重算引擎

为什么要分层

用户没碰 Excel 时，整个技能只占 SKILL.md 头部那几十字；一旦说「改下这张表」，才逐层把正文、formulas.md、recalc.py 取进来。能力可以很大，context 始终很小。

P12 · 为什么模型需要 Skill【重点】

六大结构性缺陷 —— 都源自训练方式本身

模型能力越强、翻车越多 —— 「能做」和「做得好」之间，有一道根本的鸿沟。

1

知识时效性断层

训练有截止日期。截止之后的库版本、API 变更、新规则，模型一概不知。

例

某 Python 库今年升到 v3、API 全变了，模型仍按一年前的 v2 写法生成代码 —— 一跑就报错。

2

私有知识不可获取

企业内部口径、业务流程、专有方法论从未进入训练语料 —— 模型根本没见过。

例

「单方成本」到底含不含税、按哪个口径算 —— 这是公司内部定义，模型只能瞎猜。

3

会踩坑（毒性遗产）

训练数据里混着大量错误写法，模型学了也会照犯 —— 这是训练的「副作用」。

例

网上大量 Word 代码用 WidthType.PERCENTAGE 设表格宽度，模型照学 —— 实际导出宽度全错。

4

缺质量标准与规范

不知道什么算「好」、输入输出该长什么样 —— 没有契约，结果就飘。

例

同样让写「分析报告」，模型有时给 3 段、有时给 3000 字，结构每次都不一样。

5

不知该用什么工具

同一个任务有多条技术路径，模型不知道哪条是团队认可的最佳实践。

例

查数据该写 SQL 还是调 API？模型可能选了最差的一条 —— 而团队明明有规定。

6

缺样例参考

没有「正确长这样」的范本，模型只能凭概率猜，每次输出形态都不一致。

例

让出一份「投标评分表」，模型从没见过标准范本，只能拼凑 —— 给个样例质量立刻不同。

P13 · Skill 如何逐一解决【重点】

用确定性的规则，覆盖概率性的推断

Skill 不是教模型新知识 —— 是把模型「凭概率猜」的地方，换成「按规则做」。

六大缺陷		Skill 的解法
① 知识时效性断层	→	`references/` 随时更新 —— 知识与模型解耦，改文档不用改模型。库升级到 v3，只改 `references/api.md`，AI 立刻按新版写。
② 私有知识不可获取	→	`SKILL.md` 编码私有流程、方法论、业务标准 —— 把没见过的写进来。把「单方成本=不含税÷可售面积」直接写进 SKILL.md，AI 不再猜。
③ 会踩坑	→	用确定性规则明确「永远这样、永远别那样」—— 排除训练数据的干扰。 docx Skill 写死「Always DXA, never PERCENTAGE」，覆盖错误倾向。
④ 缺质量标准	→	精确定义输入输出规范与验收口径 —— 给模型一份契约。规定报告必须六段式、每段结论前置 —— 每次产出结构一致。
⑤ 不知用什么工具	→	`scripts/` 把最佳技术路径编码成脚本 —— 不留选择空间。查数固定调 `query.py`，AI 不用纠结写 SQL 还是调 API。
⑥ 缺样例参考	→	正文 / references 内置范本 —— 相当于一份「永久 Few-shot」。 references 里放一份标准评分表样例，AI 每次照着出。

六大缺陷一个统一视角：凡是模型「靠概率猜不准」的地方，Skill 就用「确定性」把它钉死。

P14 · 案例解析一【重点】

Anthropic 自带通用 Skill：docx / xlsx

官方 Skill 直接验证了理论 —— 它们写的不是「知识」，是给模型排错的硬规则。

docx Skill 正文里的真实规则

Always use WidthType.DXA, never PERCENTAGE

模型常因训练数据混入而用 PERCENTAGE，生成的表格在 Word 里宽度错乱。

Never use unicode bullets（•、▪）
—— 用 Word 原生列表样式

直接打 unicode 符号看似「能用」，实际不是真列表，导不出大纲、改不动层级。

xlsx Skill：公式必须用引擎重算，
不要手填计算结果

模型爱直接把算好的数填进单元格 —— 数据一变，整张表就错。

对应缺陷 ③ 会踩坑

这些规则不增加任何「能力」—— 它们存在的唯一目的，就是抵消训练数据里的错误倾向。

为什么是「给 AI 用」的证据

这些话人类开发者根本不需要 —— 人不会犯 WidthType 这种错。它只对 AI 有意义。

P15 · 案例解析二【重点】

真实业务 Skill：成本问数

把成本经理的专业判断、口径校验、归因框架 —— 显性化成一套可执行规则。

5 步执行主线 —— 理解诉求 → 口径校验 → 取数 → 五差归因 → 结论

把成本经理「怎么想这道题」的隐性流程，写成模型每次都走的固定路径。

例 · 用户问「A 项目土建为什么超了」

AI 不直接答 —— 先按主线走：确认是哪个口径的「土建」→ 取目标 vs 实际 → 拆五差 → 才下结论。

口径校验 —— 含税 / 不含税、单方口径、统计范围逐项确认

同一个「金额」可以有好几种口径，不校验，答出来的数就没法用。

例 · 同一个「单方成本」

含税 ¥4,800 / 不含税 ¥4,250；按建筑面积还是可售面积，结果差一截 —— Skill 强制先问清再算。

五差归因框架 + 深挖决策表

差异从哪来、下一步往哪查 —— 给模型一张「按业务路径继续追问」的表。

例 · 超支 200 万怎么拆

五差：量差 / 价差 / 标准差 / 范围差 / 其他。查表 → 发现是「标准差」（精装标准提高）→ 继续下钻该科目。

逐条对照六大缺陷

私有知识 —— 成本口径、归因框架进 SKILL.md
质量标准 —— 口径校验就是输出规范
样例 —— 决策表内置「该怎么追问」的范本

一句话

Skill 把一位资深成本经理的脑子，沉淀成了文件 —— 换谁来问，AI 都按同一套专业方法答。

P16 · 实战开场前 · 黑话速查

售楼业务 10 个词,30 秒看完

三个实战都用真库售楼数据 —— 先给"非售楼专业"的观众一份小词典,后面看代码 / SQL / DSL 不卡壳。

交易状态链(同一房号会经历)

小订:意向阶段、付小额定金
认购:正式认购、付认购款
签约:合同签订(草签 → 网签)
网签:房管局备案,合同生效

单据状态

激活:有效单 — 真实业绩
关闭:作废/转换 — 不计业绩
业绩统计前必须先过滤 Status=激活,否则关闭单也算进去 = 业绩翻倍

人员 / 数据库字段

置业顾问(zygw):销售员,负责接待+成交
成交总价(cjTotal):一笔单的实际成交金额
建面(cjBldArea):建筑面积,含公摊

货值表的"层级"陷阱

货值表 dwd_s_projectvalueabledetail 同一笔货值在 Level=1/2/3 三层各存一份等额金额(楼栋明细/分区明细/版本总计)
IsBenchmark=1:基准版货值(对外口径用这版)
不锁 Level 直接 SUM = 同一笔货值算 3 次(实战 B P40 真实 bug)

看不懂某个词时翻回这页 —— 不熟悉售楼业务也能完整看懂三个实战。

P17 · 实战 A · 业务 & 架构设计现场实战

售楼销售台账查询 · API 模式

业务复刻明源云售楼系统的「销售台账」界面 —— 项目筛选、销售状态、签约状态、网签日期、置业顾问，一行 = 一笔交易。

业务设计 · 一个统一台账端点 /sales/ledger

用户问

"光谷天地一期
1208 有哪些交易"

→

Skill 胶水

人话→端点+参数
scripts/query.py

→

FastAPI

/health
/sales/ledger

→

真库 MySQL

认购宽表 142
+合同宽表 51
UNION

🏗️ 架构设计 · 两层

API 层（提前做好）：FastAPI + pymysql 直连真库，dwd_s_order UNION dwd_s_contract 合成统一台账，对外仅暴露 /sales/ledger 一个查询端点。
Skill 层（现场手搓）：YAML description 写触发词，query.py 把子命令映射成 HTTP query string —— 不连数据库、不写 SQL。

🔒 关键约束 · 4 条

① 端点固化：能查什么由端点和参数决定，新维度=改代码
② 枚举校验：销售状态/合同类别/销售单状态用 enum 限定
③ 不做 mock 兜底：DB 不可用直接返 503，绝不编造数据
④ 只读 SELECT：参数走占位符，杜绝注入

把 API 文档 + 这页架构图给 Claude Code / Codex —— 它就能复刻整套设计。这就是「业务设计 + 架构设计 = 可复制资产」。

P18 · 实战 A · 真库实测现场实战

与售楼系统界面截图逐字段对齐

直连真库「售楼宽表库」 · 142 条认购 + 51 条合同 · 同一房号「小订 → 认购 → 签约」多行还原。

用户查一下光谷天地一期 1208 那栋的销售台账

Claude · 命中 sql-query-api Skill 意图：销售台账查询
项目=光谷天地，关键词=1208 $ python3 scripts/query.py ledger \
--project 光谷天地 --keyword 1208 真库连通 · 命中 4 条交易 ↓

用户 · 追问按置业顾问统计每人成交套数和总额

Claude 当前 /sales/ledger 没开聚合参数 —— 只返明细不做 GROUP BY，查不了。改 API、重启服务才行。

GET /sales/ledger · 一房多行 · 真库数据

房号2栋啊1208-住宅啊-1001

客户aaa

成交总价¥ 4,400,000

建筑面积123.12 m²

置业顾问系统管理员

销售状态（多行）小订 → 认购 → 签约

✅ 数据来源 = 生产库 · 与售楼系统「销售台账」界面截图逐字段对上

追问那一下 —— "按置业顾问聚合" 是 P22 留给实战 B 的钩子。

P19 · 实战 A · 目录结构 & SKILL 概要

把这套复制走 · sql-query-api 资产

两层目录 + 4 个核心文件 —— 贴给 Claude Code / Codex,它能照着复刻整套 API 模式 Skill。

📁 目录结构

实战A-sql-query-api/
├── api/                    # API 服务（提前做好）
│   ├── API文档.md          317 行 · 给 AI 看的接口契约
│   ├── main.py             311 行 · FastAPI 服务
│   ├── run.sh
│   └── .env.example        # 数据库连接(脱敏)
└── skill/sql-query-api/    # Skill 胶水（现场手搓）
    ├── SKILL.md            150 行 · 触发词+流程
    └── scripts/
        └── query.py        306 行 · 子命令式 CLI

🤖 SKILL.md 概要 · 关键 6 段

① YAML description · 写触发词(销售台账/合同/认购/光谷天地…)
② 前置条件 · API 必须在 :8077 跑通,DB 必须连得上
③ 端点清单 · /health · /sales/ledger(枚举参数表)
④ 调用流程 · 理解意图 → 抽取参数 → 调 query.py → 整理回答
⑤ 边界声明 · 不连库不写 SQL · 503 时如实告知不编造
⑥ 典型对话 · 4-6 个真实问句示例

API文档.md 同样关键 —— 端点 + 参数枚举 + 响应字段 + 真库示例,Claude Code 主要靠它复刻 API。

API文档.md + SKILL.md 这两份契约写好,Claude Code 自动产出 main.py 和 query.py。

P20 · 实战 A · CLI 设计 & 典型问答

CLI 设计 · `query.py` 子命令把人话→HTTP

CLI 是 Skill 和 API 之间的薄胶水 —— 一个子命令对应一个端点,枚举参数防 AI 乱传。

子命令	映射端点	关键参数(枚举/范围)
`health`	GET /health	无 — 探活
`ledger`	GET /sales/ledger	--project · --keyword · --sale-status {小订/认购/预认购/签约} · --order-status {激活/关闭} · --contract-type {草签/网签} · --sign-start/end · --consultant · --limit 1-200

💬 典型问答 · 3 个真人会问的问题

Q1 · 单房号交易历史

"光谷天地一期 1208 那栋的销售台账"

$ query.py ledger \
  --project 光谷天地 \
  --keyword 1208

→ 4 行(小订/认购/签约)

Q2 · 按日期范围筛交易

"2026 年 4 月签约的合同"

$ query.py ledger \
  --sale-status 签约 \
  --sign-start 2026-04-01 \
  --sign-end 2026-04-30

→ 9 条已签约合同

Q3 · ❌ 答不了的问题

"按置业顾问统计成交套数"

# /sales/ledger 没开
# group_by 参数
$ query.py 无法处理

→ 端点固化 → P22 伏笔

子命令 + 枚举参数 是 API 模式的灵魂 —— 接口窄、AI 不会乱传,但也意味着新维度必须改代码。

P21 · 理论 Callback

刚才这个 Skill，印证了前面的理论

把实战 A 的产物拉回来，对照 P10–P13 的理论点 —— 逐条打钩。

✓

固化了工具调用？

query.py 把「子命令 + 参数」映射成「API 端点 + query string」—— 调用方式被钉死。对应 P10-①

✓

固化了业务 SOP？

SKILL.md 写死调用流程：理解需求 → 抽参数 → 调脚本 → 整理回答。对应 P10-②

✓

消除了「业务转技术」偏差？

「海伦广场已审核合同」→ 精确的端点 + 参数，不靠模型每次猜。对应 P10-③ / P13-④

✓

沉淀成可复用资产？

description 决定能否触发，正文是契约，脚本是最佳路径 —— 三级结构齐全。对应 P10-④ / P11

一个不到百行的 Skill，把业务经验、工具调用、输出契约全固化了 —— 这就是「Skill 是给 AI 用的可复用资产」。

P22 · 留个伏笔

两个简单问题，API 答不了

实战 A 跑得很顺 —— 但只要用户多问一步，API 模式的天花板就出来了。

❌ 问题 ①

"按置业顾问统计每人的成交套数和成交总额"

根因：/sales/ledger 只返明细，没有 group_by 参数，也没有 sum/count 度量。

❌ 问题 ②

"光谷天地的成交总价加起来是多少"

根因：API 端点是写死的明细查询，没开聚合参数 —— 想加得改代码、加端点、重启服务。

API 模式的本质局限

· 端点+参数 = 写死的契约
· 新维度 = 改代码 + 重启 + 发版
· 多维度交叉 / 下钻归因做不了

下一章用 CLI + 本体解决

· DSL 让 AI 现场「拼」查询，不调死端点
· 本体 schema 写死业务口径(口径护栏)
· 同一个问题，待会用 aggregate 当场答出来

这两个问题 先记住 —— 第三章用 DSL + 本体当场把它们答出来。