把 Agent Skill 放在项目文件夹外面
BaseHalf 把一份 skill 装到 ~/.claude 和 ~/.agents。它不会进仓库，我们也不会替你改 CLAUDE.md 或 AGENTS.md。
我们见过的团队，最后几乎都会把 Agent 说明写进仓库。一份描述界面的 CLAUDE.md。一份写着布局存在哪的 AGENTS.md。下一次 PR 里这些行又出现一遍，从没打开过 BaseHalf 的同事也得跟着合。
我们希望 Claude Code 和 Codex 能读懂画布，又不要把每个项目都变成 BaseHalf 说明书。所以教 Agent 理解 .bh/ 的那份 skill，放在这台机器上，不放进你要提交的文件夹。
装什么，装到哪里
第一次打开文件夹时，BaseHalf 会提议安装 skill。可选 Install、Not Now，或 Don't Ask Again。在你回应之前，提示会一直留着。
安装会把 BaseHalf 自带的那份 skill，链到这台 Mac 上 Agent 本来就会看的位置：
- Claude Code：
~/.claude/skills/basehalf/ - Codex 以及其他读共享位置的 Agent：
~/.agents/skills/basehalf/
它不会进项目文件夹。我们也不会写入 CLAUDE.md 或 AGENTS.md。之后可以在命令面板里跑 BaseHalf: Install Agent Skill 或 BaseHalf: Remove Agent Skill。每次更新 BaseHalf 都会刷新它自己的那份副本，不必为了跟上版本再手动重装一遍。
Skill 覆盖怎么读 .bh/、描述、连接、选中，以及用来生成的草稿。因为它是 skill，你在别处启动的 Agent 在任务需要时也能加载，不只限于 Agent Area 里的会话。
机器上的 skill，仓库里的工作
这道分界是故意的。
| 留在这台机器上 | 留在仓库里 |
|---|---|
~/.claude 与 ~/.agents 下的 BaseHalf skill | 源码、笔记和普通项目文件 |
| 服务商密钥（加密存在这台 Mac） | 写进文件的 upstream 列表 |
.bh/ 里不进 git 的布局元数据 | 该提交的 Markdown frontmatter 或 mirror 里的 upstream |
| 这台 Mac 的 skill 安装状态 | 同事不装 BaseHalf 也需要的东西 |
把工作区界面说明塞进每个仓库，会污染 diff，也把同事绑死在同一种工具上。机器本地的 skill，把「怎么读 BaseHalf」放在真正需要它的 Agent 旁边。项目文件留下工作本身：代码、笔记，以及下次 clone 仍该在的 upstream 列表。
Agent 仍然用自己的工具读普通项目文件。BaseHalf 从不把整个工作区塞进 prompt。Skill 是通往 .bh/ 和选中的地图，不是你已经提交的那些文件的替代品。
换一台机器时的代价
新 Mac 不会自动带上这份 skill。在 BaseHalf 里打开文件夹，再回应一次安装提示，或跑命令面板里的命令。在那之前，这台机器上的 Agent 拿不到 skill 里那些 BaseHalf 专用指引，状态栏也会说明它们看不到你的选中。
这就是把 skill 留在仓库外的代价。我们接受。从没安装 BaseHalf 的同事，不必在每个 PR 里审界面文档。装了的人，在自己机器上共用一份随应用更新的 skill。
该进 git 的仍是工作本身：说明文件依赖什么的 upstream 列表、你写的笔记、你改的代码。选中留在打开窗口期间的 .bh/cache/。布局不进 git。Skill 留在 home 目录下。
我们不再通过每个仓库分发 BaseHalf 的界面说明。机器上一份 skill。项目里普通文件。Claude Code 和 Codex 学会这张地图，文件夹却不必变成产品手册。