Three AI coding tools on one machine, and each one reads its rules, skills and agent instructions from its own folder. I keep a single copy of all of it in one repository, and a small Rust CLI I wrote, ai-dotfiles, installs it into Claude Code, GitHub Copilot and Cursor.
The files are simple to copy. What needed design was updating and removing them later without wiping the ones I edit by hand, and the manifest below does that.
Three tools, three folders
ai-dotfiles manages ~/.claude, ~/.copilot and ~/.cursor. Each one gets the same two files at the top:
AGENTS.md, the shared contract: priority order, how work is verified, safety guardrails.CLAUDE.md, which pulls in@AGENTS.mdand adds what applies to only one runtime.
Rules and agent definitions sit under each root too. The CLI also writes starter files for hooks and MCP servers: ~/.claude/settings.json, ~/.copilot/hooks/hooks.json, ~/.cursor/hooks.json, ~/.cursor/mcp.json and ~/.copilot/mcp.json. It merges its servers into VS Code's mcp.json as well; when a name collides, the entry I wrote there wins.
Cursor is the odd one out. It keeps its global rules in a settings screen called User Rules, not in a file anything can install. So the CLI installs a template at ~/.cursor/instructions/user-rules-template.md, and after an install or update I paste it in by hand.
One copy of every skill
Skills are installed once, under ~/.claude/skills. Copilot can read Claude skills from that location, so there is no second copy to keep in sync.
The binary carries 53 skill folders of its own, and a file called external-skills.toml declares 124 more from other repositories. Each external source is pinned to a full commit SHA, never a branch or a tag, and can carry a SHA-256 checksum of its SKILL.md. If one source fails to download during an update, the CLI warns and keeps the copy already installed. A failed download costs me an update, not a skill.
Some skills and rules are adapted from other people's work, mainly obra/superpowers (MIT) and flutter/agent-plugins (BSD-3-Clause). The upstream commits and license notices are recorded in a NOTICE.md that installs next to the skills.
Three commands and a manifest
ai-dotfiles install
ai-dotfiles update
ai-dotfiles debloat
I edit these folders by hand too, which is why update and debloat never guess. Each tool root gets an _meta.md file whose YAML front matter records the version and every file and directory the CLI wrote. Both commands treat that list as the source of truth.
update works out which files the current version should install, deletes tracked files that dropped out of that set, writes only what is new or changed, and rewrites _meta.md last, so the manifest lists what is really on disk. debloat removes everything the manifest lists, then the manifest itself.
A file I added myself is not in the manifest, so neither command touches it. Cleanup never follows a symlinked directory. And install refuses to run over an existing installation; it tells me to run update instead.
A version of the binary is a version of my setup
The files under static/ are embedded into the binary at build time, so v3.2.2 installs exactly the rules and skills that were in the repository when that tag was cut. Pinning a version is one command:
cargo install --locked --git https://github.com/rafaelcmm/ai-dotfiles.git --tag v3.2.2 ai-dotfiles
Before syncing files, update checks GitHub for a newer release. If there is one, it downloads the binary for my platform, confirms the release's SHA256SUMS lists that asset, installs it and runs update again on the new version. A network error there doesn't block the sync.
Releases go through scripts/release.sh, which refuses a dirty working tree or any branch other than main. Then it runs cargo fmt --check, cargo clippy with warnings as errors, the offline tests and the networked integration tests, and only after all of that does it bump the version and tag. v3.2.2 is the 53rd version tag since the first commit, in April 2026.
The hook that keeps agents inside the repo
The CLI also installs a few hook scripts. One of them, guard-paths.sh, refuses agent writes outside the current repository. It has four exemptions, and each one comes from how Claude Code works:
- a Markdown file directly inside Claude Code's per-project memory folder;
- a Markdown file directly inside its plans folder;
- any file in the session's scratchpad;
- the folder the session was started in. It has to be inside my home directory without being the home directory itself, have no hidden folder in its path below my home, and contain the working directory.
Paths are resolved before matching, so .. and symlinks can't widen any of them.
What the rules ask of the agents
The rules ai-dotfiles installs decide how the agents work with me: plan before building, show evidence before calling something done, and never send anything in my name. How they work is in Spec-first with AI agents.
The code is MIT licensed and public at github.com/rafaelcmm/ai-dotfiles. If you only open one folder, open static/: that is the setup itself.

