CLAUDE.md 为什么会越写越长
刚开始用 Claude Code 时，CLAUDE.md 往往只有几行：怎么构建、怎么跑测试。用了几个月，它就慢慢变成了一份「项目百科」：部署步骤、接口约定、数据库表说明、发版检查清单、踩过的坑，全都往里堆。
问题在于，CLAUDE.md 每次开会话都会被整份读进上下文。你今天只是想改一个按钮的文案，Claude 也得先把几百行部署手册读一遍。结果是两件事：留给真正工作的上下文变少了；规则太多、太杂，关键的那几条反而容易被忽略。
另一个常见的烦恼是 skill 散落各处。同时用好几个工具、在好几台电脑上干活，同一份「发版流程」可能存了三四份，这份改了、那份忘了，最后谁也说不清哪一份是最新的。
Claude Code 的 Skills 正好能解决这两件事：它是一个个带说明的文件夹，平时只占用一行简介，Claude 判断当前任务用得上时才去读完整内容。下面在一台常开的 Mac mini 上把这套结构搭起来。
准备清单
- 一台常开、不休眠的 Mac mini，已安装 Claude Code 并用你自己的账号登录。
- 能用 SSH 或 UU 远程连接登录这台机器，终端里装好 git 和 tmux。
- 一个正在维护、CLAUDE.md 已经比较长的项目仓库。
步骤一：给 CLAUDE.md 做一次体检
SSH 登录 Mac mini，进入项目目录，先看看它到底有多长：
- 运行
wc -l CLAUDE.md看行数，再从头到尾读一遍。 - 把每一段归到两类里：每一轮都必须遵守的（构建和测试命令、不能碰的目录、提交信息格式、「改完先跑测试」这类硬规矩），和只在某类任务里才用得上的（部署手册、某个服务的接口说明、发版检查清单、排错笔记）。
- 第一类留在 CLAUDE.md，尽量写成短句；第二类就是接下来要拆出去的 Skills 候选。
一个简单的判断标准：如果一段内容一周只用得上一两次，它就不该每轮都占着上下文。
步骤二：把参考文档写成 Skill
一个 Skill 就是一个文件夹，里面必须有一个 SKILL.md。它可以放在两个位置：
- 项目内：
.claude/skills/<名字>/SKILL.md，跟代码一起进 git，团队成员拉下来就能用。 - 个人全局：
~/.claude/skills/<名字>/SKILL.md，对这台机器上的所有项目生效。
以「发版前检查」为例，在项目里新建 .claude/skills/release-check/SKILL.md，开头是一段 YAML 头信息：name 写 release-check，description 写清楚什么时候该用它，比如「准备发新版本、打 tag、更新版本号或更新日志时使用」。下面的正文才是具体步骤：核对版本号、更新 CHANGELOG、跑完整测试、确认构建产物、最后再打 tag。
description 是最关键的一行。Claude 平时只看得到每个 skill 的名字和这句说明，靠它来判断要不要加载全文，所以要写「什么场景用」，而不是只写「这是什么」。
篇幅很长的资料，比如完整的接口字段表，可以放在同一文件夹下的 reference.md，在 SKILL.md 里写一句「需要字段细节时再读 reference.md」；配套的检查脚本也可以放进来，比如 scripts/check.sh，让 Claude 直接执行，而不是每次重新写一遍。
拆完之后，回到 CLAUDE.md，把对应的长段落删掉，只留一句指引即可，例如「发版相关流程见 release-check skill」。
步骤三：建一个 skill 主库，用软链接接入
多台电脑、多个项目都要用的通用 skill，不要到处复制，集中放在一个 git 仓库里：
- 在 Mac mini 上建目录
~/agent-kit，里面放skills/子目录，每个 skill 一个文件夹，然后git init并推到你自己的私有远程仓库。 - 把主库接到 Claude Code 的个人目录：如果
~/.claude/skills里还没有东西，可以先把它移走备份，再执行ln -s ~/agent-kit/skills ~/.claude/skills；也可以只为单个 skill 建链接，比如ln -s ~/agent-kit/skills/release-check ~/.claude/skills/release-check。 - 如果你还用其他也支持同类 SKILL.md 格式的工具，同样用软链接指向这份主库，具体读取目录以各工具自己的文档为准。
- 以后改 skill 只改
~/agent-kit里那一份，git commit后推送；其他电脑上执行git pull就同步了。
这样「同一个 skill 存了好几份」的问题就从结构上消失了：只有一份文件，其他位置都是指向它的链接。
步骤四：验证 skill 能被正确调用
- 在 tmux 里开一个新会话：
tmux new -s skills，进入项目目录运行claude。 - 先直接问它：「你现在可以使用哪些 skills？分别在什么情况下用？」确认刚才写的 skill 出现在列表里，说明也读对了。
- 再给一个符合 description 的任务，比如「准备发 1.4.0 版本」，观察它是否先加载 release-check、按里面的顺序逐项检查。
- 如果它没有用上，大多是
description写得太泛。把触发场景写得更具体，再开一个新会话重试。
步骤五：让主库在常开的 Mac mini 上保持最新
Mac mini 一直开着，最适合当这套 skill 的「中心」：
- 在 Mac mini 上用
crontab -e加一条每天早上执行cd ~/agent-kit && git pull --ff-only的任务，其他电脑推上去的修改会自动同步过来。 - 主库里只放流程和说明，不要放任何密钥、令牌或账号信息；需要凭据的步骤写成「从环境变量读取」，并在仓库里加好
.gitignore。 - 每隔一段时间回头看一次 CLAUDE.md，新加进去的长段落及时挪到 skill 里，让它一直保持简短。
为什么放在一台常开的新加坡整机上
Skills 和 CLAUDE.md 的价值，在于每次会话都在同一套规则下工作。放在笔记本上，合盖、换网络、系统更新都会打断长会话，几台电脑之间的配置也容易各走各的。放在一台常开的 Mac mini 上，主库、项目和 tmux 会话都在同一个地方，你从哪台设备用 SSH 或 UU 远程连接进去，看到的都是同一个现场。
Zumac.Ai 提供的就是这样的环境：位于新加坡家庭宽带上的实体 Mac mini M6，整机独享（一人一台物理机），7×24 在线，支持 SSH 和 UU 远程连接，FileVault 全盘加密，退租时抹机重装。新客户整机租用 ¥999/月起，季付、半年付、年付有折扣。实际延迟取决于你本地的网络线路，建议先租一个月，把自己的 skill 主库和工作流跑通。
小结
- CLAUDE.md 只留每一轮都要遵守的短规则，长资料不要每轮都读。
- 只在某类任务里才用的内容写成 Skill，
description写清楚「什么时候用」。 - 通用 skill 集中放进一个 git 主库，用软链接接入，改一处、处处生效。
- 在常开的 Mac mini 上定时
git pull，主库里不放任何密钥。
