把对话沉淀成技能：让昨天那 28 分钟变成今天的 /命令

昨天我花了整整 28 分钟带着 Claude 把我们 OAuth 刷新令牌流程过了一遍。Token 端点、leeway 窗口、两个自定义 claims、那个仅 staging 环境才有的怪癖。Bug 找到、修掉、上线。

今天早上，姊妹服务里几乎一模一样的问题。我打开一个新对话。Agent 对昨天毫无记忆。又是 28 分钟。

这不是 Anthropic 的设计缺陷。无状态 Agent 才是正确的默认值——你不会希望昨天那个错的假设缠着今天的对话。解法不是"给 AI 记忆"，解法是给你自己记忆，存在 Agent 明天会读到的地方。

那个地方就是 Skill。

Skill 是什么 —— 以及它该住在哪里

一个 Skill 就是一个 Markdown 文件，仅此而已。Cockpit 只关心两件事：文件正文（成为 /skill-name 的 system prompt）和指向它的绝对路径。

路径是最重要的设计选择。 Anthropic 的官方约定是把 skills 放在 ~/.claude/skills/。Cockpit 故意不这么做。我们不扫你的 home 目录、不预留某个文件夹名、不强占任何位置。你的 skills 想住哪里就住哪里：

• ~/Notes/Skills/oauth-debug/SKILL.md —— 跟你的个人笔记放一起
• ~/Documents/team-playbooks/oauth-debug/SKILL.md —— 在同步目录里
• ~/Work/our-handbook/skills/oauth-debug/SKILL.md —— 在团队 git 仓库里
• ~/Obsidian/Vault/Skills/oauth-debug/SKILL.md —— 在你的 Obsidian 库里
• ./.claude/skills/oauth-debug/SKILL.md —— 偏好 Anthropic 风格也行

每个 skill 是独立的子文件夹，里面放一个 SKILL.md（Anthropic 约定），文件夹名就是斜杠命令名。为什么一个 skill 一个文件夹？因为 skill 经常会带"伙伴文件" —— 示例对话、参考小抄、一个被 agent 调用的 Python 辅助脚本 —— 文件夹给它们一个自然的家。

为什么这事重要： 你的知识本来就住在某个地方。你有 vault、有笔记软件、有文档仓库、有自己经营多年的"Skills"目录。强迫 skills 进 ~/.claude/skills/ 等于让 Cockpit 跟你已有的体系打架。我们选择只注册指针，不搬运文件。

两步流

第 1 步： 在 你的 知识库里写 SKILL.md，路径随你定。

第 2 步： 在 Cockpit 的 Skills 侧边栏点 + Add Skill，粘贴绝对路径。Cockpit 把它存进 ~/.cockpit/skills.json（一个文件、一份指针列表，备份方便）。

完事。这个 skill 现在出现在你的斜杠补全里。源文件你想用什么编辑器改都行 —— Cockpit 监听文件变化、保存即生效，无需重新 import。

在此基础上，Cockpit 给你的额外能力：

• Skills 侧边栏：每个已注册技能的名称、描述、图标、源路径、最后使用时间
• 斜杠补全：在对话里打 /，你的技能跟内置 /qa、/fx、/review 混排出现
• 有效性检测：源文件不见了（你改名、移动了 vault），红色 "Invalid" 徽标提醒你 —— 改路径就能恢复
• 预览：点任意技能可以全屏渲染 markdown 或查看原始源码

沉淀循环（真正的工作流）

诀窍不是手写 skills。诀窍是让刚刚奏效的对话自己写 skill 给你。

每一次成功的对话末尾，加三句话：

第 1 句：浓缩

总结一下我们刚才搞清楚的 OAuth 刷新流程。 要具体：文件路径、真正的根因、下次该先查什么。

Agent 现在把整段对话拉到了工作集里。它知道什么是关键。

第 2 句：编码

把它写成一个 SKILL.md，我要放进我的知识库 ~/Notes/Skills/oauth-debug/SKILL.md（或者你自己习惯的位置）。

形态：被调用时接收一个问题陈述，按今天的同样顺序走完同样的诊断步骤， 第 4 步之前不许提修复方案。控制在 40 行以内。

你会拿到类似这样的输出：

---
name: oauth-debug
description: 用我们的诊断剧本排查 OAuth 刷新令牌失败。
---

你负责诊断我们鉴权栈中的 OAuth 刷新令牌失败问题。

当用户描述故障时，按以下顺序执行：

1. 确认是哪个环境（dev / staging / prod）。Staging 有 60 秒的 leeway
   窗口，prod 没有。
2. 读 `auth/refresh.ts`，找出验证了哪些 JWT claims。我们要求同时
   存在 `sub` 和 `tid`，绝不能只验 `sub`。
3. 索取失败的 access token（或脱敏版）。解码 header 检查 `alg`，
   必须 RS256，永远不允许 HS256。
4. 看 `auth/keys.ts` 里 JWKS 的缓存 TTL。两年里有 3 个 bug 来自
   过期的 JWKS 缓存。
5. 只有走完上面 4 步，才允许提修复方案。

第 5 步前绝不修改代码。如果用户提前要修，复述剩下的诊断步骤让用户选。

第 3 句：保存

存到那个路径。

如果你给了 Agent 对你知识库目录的写权限，它会自己建文件。否则从对话里复制粘贴到你的编辑器 —— 效果一样。文件现在住在你的笔记里、被你已有的搜索索引、被你已有的 git 版本化、被你已有的 Dropbox / iCloud / Syncthing 同步。它不是 Cockpit 的数据。

然后注册它。 在 Cockpit 的 Skills 侧边栏点 + Add Skill，粘贴绝对路径：

/Users/you/Notes/Skills/oauth-debug/SKILL.md

（一次性，5 秒钟。）从此 /oauth-debug 出现在所有对话的斜杠补全里。源文件你在哪儿改都行 —— 你的编辑器、另一台机器、队友的 PR —— Cockpit 在下一次文件系统事件时自动捡起来。

明天早上

/oauth-debug 刷新令牌只在 staging 偶发失败。

Agent 自动进入你昨天训练过的同款姿态。同样的检查、同样的顺序、同样的"先别急着修"。不是因为它记得——而是你把昨天写下来了，写在了它会再读的地方。

昨天的 28 分钟，今天浓缩成一次 30 秒的调用。

值得"立此存照"的三种 skill 形态

不是每段对话都值得做成 skill。值得的那些通常是这三类：

诊断型 —— /oauth-debug、/db-deadlock、/cors-issue、/flaky-test。把一套排查流程冻结成 checklist，Agent 不用再瞎猜。

约定型 —— /our-pr-style、/our-test-style、/our-error-handling。把团队的部落知识冻结下来。新人入职第一天敲 /our-pr-style，Agent 写出来的 PR 一次过 review，不用 4 轮 nitpick。

Onboarding 型 —— /our-stack、/our-deploy-flow、/where-does-X-live。给新 Agent 解释你的代码库。这一类杠杆最高——每一次新对话都从一张正确的地图开始。

不属于这三类的对话，多半是一次性的，不必沉淀。

Skill 作为团队资产

正因为 skill 只是 你选定路径下 的 markdown 文件，团队资产这一层几乎是白送的。挑一个团队已经信任的仓库就行：

~/Work/our-handbook/skills/
├── README.md             # 怎么写技能、怎么注册到 Cockpit
├── oauth-debug/
│   ├── SKILL.md
│   └── examples.md       # 可选：技能可以引用的伙伴文件
├── our-pr-style/
│   └── SKILL.md
└── our-deploy-flow/
    ├── SKILL.md
    └── runbook.md

Skill 因此可以 diff、可以 review、可以 git blame。Senior 那句"始终做 X、绝不做 Y"不再是一条 Slack 私信，而是一个有 reviewer 的 PR。新人 git pull 完，点 3 下 + Add Skill，团队的隐性知识在他第一天结束前就出现在斜杠菜单里。

Cockpit 的局域网共享评审页（参见上一篇博客）让内循环更紧：在对话里写出 skill、把评审页面分享到局域网、队友逐行评论、把评论喂回 Agent 作为上下文、Agent 修订、你 commit。

关键是：Skill 不是把团队的知识复制了一份，而是引用了它。 当 handbook 更新，skill 就更新。只有一个事实来源，而且就是你团队本来存放事实的地方。

进阶：用 skill 写 skill

有了第一个 skill，下一步可以写一个 meta-skill：

/distill 读这次对话最近 50 条消息。如果发现任何重复出现 3+ 次的
模式，给我提一个 SKILL.md 草案。先别自动保存，给我看草案再说。

从此你的 Skills 侧边栏会自己慢慢长出来，从你真实进行的对话里长出来。Cockpit 内置的 /qa、/fx、/review、/commit 是有主见的默认值——但一年后你侧边栏里最好用的那些 skill，多半不是你手写的。

背后的原则

无状态 Agent 是对的。它在每段对话之间重置自己，因为这样昨天那个错的假设才不会污染今天的对话。

但你的团队不是无状态的。团队会学习。问题只是：那些学习到的东西，是住在三位工程师的脑子里，还是住在 ./.claude/skills/ 下 12 个被 review 过的 Markdown 文件里。

Skills 就是把这个选择显式化的方式。

---

npm i -g @surething/cockpit · GitHub · 在线体验