Skills：把经验沉淀成可复用能力

前两章分别处理了工具与判断：TIRx 让编译器本身变成 Agent 可调用的分析器，Humanize 让 reviewer 不断追问证据。但 reviewer 如果只有“检查测试是否跑了”的通用清单，仍然问不出关键问题：这个 fusion 在 FP8 下成立吗？这个 kernel 对应哪一行 Python？上游是否已经有人提交过类似 PR？这些问题在第 7 章 BBuf skills 里有一次真实样本的拆解；本章讨论它们的通用形式——skill（技能包）：把专家经验整理成 Agent 能在冷启动时直接调用的上下文与步骤。

学习目标

读完本章，你应当能够：

解释为什么“把文档丢给 Agent”不等于沉淀经验；
拆解 KernelWiki 与 ncu-report 两个 skill 各自解决什么问题；
说出 BBuf 的 AI Infra skills 的目录构成与五类高价值上下文（第 7 章 BBuf skills 给出完整拆解）；
按“触发条件、输入、步骤、验证、失败模式”写出一个最小 skill；
识别 skill 写作中的常见反模式，并为它设计维护方式。

为什么需要 skill

Agent 每次接到新任务，都要从零建立三样东西：任务所处的代码结构、领域里的隐含约束、以及“怎样才算验证通过”。这些信息往往散落在 README、PR 讨论、profiling 报告和资深工程师的脑子里。让 Agent 自己摸索并非不可能，但会重复支付冷启动成本，而且每次路径不同、结论不稳定。

Skill 的作用不是替 Agent 思考，而是缩短它到达“可行动状态”的距离。它把隐性的判断变成显性的检查，把“我记得这个 fusion 只在特定 dtype 下成立”变成一条可检索、可验证的规则。Humanize 的 DSA indexer 消融给了一个直接证据：同一任务、48 小时预算下，只用 RLCR 是 3.71×，加入 KernelWiki 后 6.14×，再加入 profiling skill 后 8.58×（见 Humanize 章）。这三个数字不能拆开外推，但它说明：判断流程不变时，注入正确的领域知识与 profiling 顺序，能把 Agent 从盲目搜索推向有依据的优化。和普通文档相比，skill 更强调可执行性：

形态	主要回答	局限
Prompt	这一次要做什么	难以复用，容易随会话丢失
文档	这个系统是什么	信息密度低，Agent 不知道何时该读
Skill	遇到什么信号时，按什么步骤做，如何验证	需要维护，写不好会变成新的噪声

一个 skill 可以只有一页，也可以带脚本与模板。判断它是否成立的标准不是“写得多全”，而是“另一个 Agent 在只读这个 skill 的情况下，能否做出更可靠的下一步”。

KDA 的两个样板

KDA 把两个 skill 放进了主流程：KernelWiki 提供领域知识，ncu-report 提供性能证据。它们刚好代表两类不同的沉淀。

KernelWiki：可检索的领域记忆

KernelWiki 把算子开发仓库、历史 PR 与架构迁移约束整理成可检索的知识库。例如从 Hopper 迁移到 Blackwell 时，哪些指令、内存层级或布局假设会失效，哪些写法需要重写。它的价值在于让 Agent 在提出候选方案之前，先看到“别人已经踩过的坑”和“当前硬件的约束”。

一个可用的 KernelWiki 至少要有三个特征：条目有来源（仓库、PR、文档或实验记录），结论有适用条件（硬件代际、dtype、shape、库版本），检索有入口（按算子、按架构、按技术或症状）。缺少适用条件的“经验”很容易变成过时教条。

KernelWiki 的仓库根目录本身就是 skill 目录，克隆到 ~/.claude/skills/ 即可被识别；检索入口覆盖按架构、问题、技术、症状与 kernel 类型的索引，并标注了证据边界（上游 PR 语料截至 2026-05-20，文档与榜单快照核验至 2026-08-18）。这些日期不是装饰：它们告诉你哪些结论可以直接引用，哪些需要回到当前仓库重新确认。

在 KDA 仓库里，KernelWiki 是以 pinned submodule（固定版本的 Git 子模块）引入的，原始材料以 MIT 许可分发，个别受限的 CuTe DSL 制品不随仓库分发。官方也提醒：直接克隆上游仓库可能拿到受额外条款约束的制品快照。这是「知识要可复现，但分发要合规」的一个具体范例。

ncu-report：把看报告的顺序固化

ncu-report 把 NVIDIA Nsight Compute 的分析顺序固化为六个维度，避免 Agent 一看到某个指标就下结论。六个维度是：

维度	看什么	常见误判
Occupancy 与 launch geometry	活跃 warp 数、寄存器与共享内存限制、grid 与 block 配置	occupancy 低就一定要提高
Tail effect	最后一波是否只剩少量 block，工作量是否被拖尾	只看平均利用率，忽略尾部
Stall reason	warp 在等什么：内存、屏障、指令依赖、发射	把所有停顿都归因于带宽
Tensor core utilization	矩阵指令是否真正用上，数据布局是否匹配	用了 tensor core 就一定快
SM timeline	SM 之间的负载是否均衡，是否存在空洞	只看单 SM 指标
Memory 与 cache	全局、共享、L1/L2 的命中与流量，访问是否合并	命中率高就代表没有瓶颈

这个 skill 的关键不是六行清单，而是它规定的输出：观察到什么现象、证据来自哪张表、提出什么假设、下一步做什么实验。它迫使 Agent 用证据说话，也给 reviewer 提供了可复核的接口。

从工程形态上看，ncu-report 是一套完整的目录而不只是一段提示词：入口是带 YAML frontmatter 的 SKILL.md，reference/ 里有工作流（阶段 0 到 6）、六维分析、Blackwell 指标名等文档，helpers/ 里放 harness 模板与 ncu 报告解析脚本。文档写明针对 Nsight Compute 2026.3.1 与 Blackwell（sm_100 / sm_103），CUDA 13.2 自带的是 2026.1.1；也提醒不同版本与不同 GPU 的指标名会变，ncu --list-sets 才是权威。

它还演示了 skill 应该怎样被 Agent 发现：安装到 ~/.claude/skills/<skill_name>/SKILL.md（用户级）或项目内 .claude/skills/（项目级）后，模型会在会话开始时看到 skill 的名字与描述，描述写得越像「触发信号」，误触发与漏触发就越少——这正是「触发条件」一栏在 frontmatter 里存在的原因。

一个真实样本：BBuf 的 AI Infra skills

第 7 章 BBuf skills 用一个公开仓库逐层拆过「经验怎么变成可检索的 skill」。这里只取它对写 skill 直接有用的两点：目录长什么样，以及哪些上下文必须显式写出来。

BBuf 的 AI-Infra-Auto-Driven-SKILLS 仓库把一线 Infra 工作中反复用到的上下文整理成 skill。截至 2026-10-30，仓库列出 11 个 skill，覆盖 serving 基准、容量规划、profiling 分析、流水线分析、层追踪、模型优化、代码 review 与事故分诊等方向；其中 Day-0 支持 skill 位于 model-optimization/ 子目录。具体清单以仓库为准。

方向	代表 skill	解决的问题
基准与容量	`llm-serving-auto-benchmark`、`llm-serving-capacity-planner`	跨框架比较 serving 性能；从日志解释显存、KV cache 预算与 OOM 压力
Profiling 与算子	`llm-torch-profiler-analysis`、`torch-profiler-layer-track`、`llm-pipeline-analysis`、`model-compute-simulation`	从 trace 定位 kernel 归属与重叠；估算算子形状、FLOPs 与 MFU
上游协作与运维	`sglang-humanize-review`、`sglang-prod-incident-triage`、`model-optimization/sglang-model-day0-support`	评审上游 PR、排查线上事故、支撑新模型的 Day-0 上线

与 kernel 优化最相关的，是下面几类“补 context”的工作——它们共同的特点是：知识本来就在，只是散着。

上下文	为什么必须写出来	skill 该给什么
prefill 与 decode 分开看	两者瓶颈不同，混在一个平均值里会同时掩盖问题	分别采集、分别设 baseline、分别报告
kernel 与 Python 行的映射	Profiling 看到 kernel 名，代码里写的是 `torch.nn` 调用	从 kernel 回溯调用点的路径，以及哪一档结论可以直接引用
fusion 的 dtype 与 shape 前提	融合成立依赖 dtype 提升、布局、对齐与边界 shape	成立条件与回退路径，而不是一个成功案例
上游 PR 检索	避免重复劳动，也能借到别人的测试与基准	检索关键词、仓库范围，以及如何判断“可复用”与“仅相关”
历史 PR 档案	相似算子的先例是最快的冷启动路径	检索入口、审计日期，以及引用前如何复核

最后一行是这个仓库的特色：它把 118 份模型 PR 历史档案做成了资产，按框架分目录，并提供 scripts/query.py 检索（支持按框架、模型、关键词与中英文筛选）。档案带审计日期，未评审的开放 PR 不计入，仓库明确写着“刷新源码不等于重跑 GPU 测试”。细节见第 7 章。

一个 skill 的最小结构

一个能用的 skill 至少包含六块。少一块，Agent 就可能在该停的地方继续、在该验的地方猜测。

部分	要回答的问题	写法建议
触发条件	什么信号出现时应该加载这个 skill	用症状、任务类型或文件特征描述，避免“相关时使用”
输入	需要哪些文件、命令、指标或先验知识	列出最小集合，标明哪些可缺失
步骤	按什么顺序做什么	每步一个动作，给出可直接执行的命令或检查点
验证	怎样证明这一步做对了	给出命令、阈值、容差或对照实验
失败模式	常见错误长什么样，如何回退	写负面例子与停止条件
输出与交接	留下什么证据给下一个人或 reviewer	固定文件名、字段与摘要格式

一个最小模板可以写成这样：

---
name: ncu-occupancy-triage
when: 候选 kernel 比 baseline 慢，且怀疑 launch 配置或占用率
inputs: ncu 报告、kernel 源码、目标 shape 与 dtype
---

## 步骤
1. 记录 baseline 的命令、版本与耗时。
2. 读取 occupancy、寄存器、共享内存与 block 限制。
3. 对照 tail effect 与 stall reason，提出一个可证伪的假设。
4. 只改一个变量，重跑同一基准。

## 验证
同一 shape 下重复三次，报告中位数与波动；正确性测试必须同时通过。

## 失败模式
- occupancy 提高但性能下降：检查寄存器溢出与缓存抖动。
- 只有平均值变快：检查是否牺牲了尾部或边界 shape。

## 输出
runs/<date>/summary.md，包含命令、指标、假设、结论与下一步。

写 skill 的原则与反模式

好的 skill 通常有这些共同点：只解决一个决策；把证据放在建议之前；命令与路径可以直接执行；篇幅小到能一次读完；在已知成功和已知失败的案例上都测试过；明确写出适用边界；带版本、来源与复核日期。

反模式	表现	后果	改法
百科全书	把上游文档整段搬进来	加载成本高，重点被淹没	只留做决策所需的片段，附来源
口号化	“注意性能”“仔细检查”	Agent 无法执行	换成命令、阈值与检查点
无验证	只讲步骤，不讲如何证明	错误被静默接受	每步加可观测的验收信号
单卡过拟合	只在一种 GPU 或 shape 上成立	换环境即失效	写明适用条件与回退路径
隐藏假设	默认某库版本、某布局	排错成本高	把版本、dtype、layout 写在输入里
只写不维护	链接腐烂、结论过时	Skill 变成负资产	设 owner、复核日期与失效标记

Skill 也需要评估。可以看四个指标：触发是否准确（该用的时候用、不该用的时候不打扰）、任务成功率、额外消耗的 token 与时间、过期条目的比例。最实用的评估方法是做一次冷启动对照：同一任务，一组 Agent 有 skill，一组没有，比较首次可用方案的出现时间与 reviewer 拦截率。

常见误区

即使结构写对了，落地时仍会踩到几个与“写 skill”本身无关的坑：

误区	为什么容易发生	修正
把 skill 当成更大的 prompt	一次性把所有背景塞进上下文，短期看似省事	按触发条件拆成多个小 skill，只加载当前决策需要的那一个
追求“一个 skill 管所有情况”	希望减少维护数量，却让触发条件与步骤互相冲突	一个 skill 只解决一个决策，把例外写成回退路径或拆分
装进目录就以为会生效	模型只看到名称与描述，描述不像触发信号就会漏触发	用真实任务做冷启动对照，统计触发率与误触发
把 PR 档案当当前事实	档案有采集日期，上游分支已经变化	引用前回到当前 commit 复核，过期条目标记而不是照抄

这几条的共同点是：skill 的效果取决于“何时被加载”和“加载后能否验证”，而不是文件写了多少。维护时优先修触发条件与验证段，它们比正文措辞更能改变 Agent 的行为。

本章自检

我能解释 skill 与普通文档、prompt、RAG 的区别。
我能说出 KernelWiki 与 ncu-report 各自提供的证据类型。
我能复述 prefill/decode 分开看、kernel 与 Python 行映射、fusion 前提、上游 PR 检索这四类上下文，以及 118 份 PR 档案的用途。
我能说出 BBuf 仓库里 skills 目录的条目构成。
我能写出一个 skill 的六个组成部分，并为每部分给出例子。
我能指出至少三个 skill 反模式及其修正方式。
我能说出 KernelWiki 的证据边界，以及 skill 落地时的至少两个常见误区。

练习

L3进阶60 分钟

写一个 200 行以内的 skill

目标：把一个你熟悉的经验写成 Agent 可执行、可验证的 skill，而不是一篇说明文。

任务：

从以下主题中选一个：prefill/decode 分开 profiling、kernel 到 Python 调用点映射、某个 fusion 的 dtype/shape 成立条件、上游 PR 检索。
按“触发条件、输入、步骤、验证、失败模式、输出与交接”六部分写作，总行数不超过 200 行。
至少给出 3 条可直接执行的命令或检查点，至少给出 2 个失败案例。
用一个已知正确案例和一个已知错误案例做桌面推演：按 skill 执行，能否得到预期结论？
在文件头写清适用硬件、库版本、来源与复核日期。

验收标准：

另一位同学只读 skill，不问你问题，也能复现一次判断；
触发条件具体到症状或文件特征，不出现“相关时使用”；
验证部分有命令、阈值或对照，而不是“确认无误”；
失败模式能指导回退，而不是只描述现象；
总行数不超过 200 行，且没有整段复制上游文档。

提示

先写“失败模式”，再写步骤。想一想新手最容易在哪一步下错结论，把那个判断拆成可观测的信号。命令尽量用仓库里已有的脚本或标准工具，避免依赖你本地才有的路径。最后删掉所有不影响执行的背景介绍。