Keep agent skills outside the project folder
BaseHalf installs one skill under ~/.claude and ~/.agents. It never lands in the repo, and we do not write CLAUDE.md or AGENTS.md for you.
Every team we have watched eventually put agent instructions into the repo. A CLAUDE.md that described the UI. An AGENTS.md that listed where layout lived. The next pull request showed those lines again, and teammates who never opened BaseHalf still had to merge them.
We wanted Claude Code and Codex to understand the canvas without turning every project into a BaseHalf manual. So the skill that teaches agents about .bh/ lives on the machine, not in the folder you commit.
What gets installed, and where
The first time you open a folder, BaseHalf offers to install a skill. Choose Install, Not Now, or Don't Ask Again. The offer stays until you answer it.
Installing adds a link to BaseHalf's own copy of the skill into the places agents already look on this Mac:
~/.claude/skills/basehalf/for Claude Code~/.agents/skills/basehalf/for Codex and other agents that read the shared location
It never lands inside the project folder. We do not write into CLAUDE.md or AGENTS.md. You can run BaseHalf: Install Agent Skill or BaseHalf: Remove Agent Skill from the Command Palette later. Each BaseHalf update refreshes its copy, so you do not reinstall by hand just to stay current.
The skill covers reading .bh/, descriptions, connections, selection, and drafts used for generate. Because it is a skill, an agent you start anywhere can load it when a task calls for it, not only sessions in the Agent Area.
Machine-local skill, project-local work
The split is deliberate.
| Lives on the machine | Lives in the repo |
|---|---|
BaseHalf skill under ~/.claude and ~/.agents | Source, notes, and ordinary project files |
| Provider keys (encrypted on the Mac) | Upstream lists written into files |
Layout metadata under .bh/ that stays out of git | Upstream lists that belong in Markdown frontmatter or mirrors you commit |
| Skill install state for this Mac | Anything a teammate needs without installing BaseHalf |
Workspace-UI instructions in every repo pollute diffs and couple teammates to one tool. Machine-local skills keep the how-to-read-BaseHalf knowledge next to the agents that need it. Project files keep the work itself: code, notes, and the upstream lists that should survive the next clone.
Agents still read ordinary project files with their own tools. BaseHalf never dumps the whole workspace into a prompt. The skill is a map to .bh/ and selection, not a substitute for the files you already commit.
The tradeoff on a new machine
A new Mac does not inherit the skill. Open a folder in BaseHalf and answer the install offer again, or run the Command Palette command. Until then, agents on that machine do not get the BaseHalf-specific pointers from the skill, and the status bar will say they cannot see your selection.
That is the cost of keeping the skill out of the repo. We accept it. Teammates who never install BaseHalf are not forced to review UI docs in every pull request. Teammates who do install it get one shared skill on their machine, updated with the app.
What still belongs in git is the work: the upstream lists that say what a file depends on, the notes you write, the code you change. Selection stays in .bh/cache/ for the open window. Layout stays out of git. The skill stays under home.
We stopped shipping BaseHalf's UI instructions through every repository. One skill on the machine. Ordinary files in the project. Claude Code and Codex learn the map without turning the folder into a product manual.