{"slug": "the-home-repo-pattern", "title": "The Home Repo Pattern", "summary": "A new reference guide published on the AI Coding Dictionary site describes the \"Home Repo\" pattern, in which developers keep one repository holding their skills, AGENTS.md file and shared docs, with navigation pointers to their other repos so a coding agent can open or clone them as needed. The guide argues the setup solves the problem of agents started in a single repo seeing only that repo, and supplies a copyable setup prompt that has the agent inventory every git repo under the home directory, sort shared material into four buckets (shared, duplicate, repo-specific, installed), and apply nothing until the user approves a plan table and the Home Repo's AGENTS.md.", "body_md": "# The Home Repo Pattern\n\nOne repo for your skills, AGENTS.md and shared docs, with pointers to your other repos. A reference, with a setup prompt you can copy.\n\n## On this page\n\nA [Home Repo](https://www.aihero.dev/ai-coding-dictionary/home-repo) is one repository that holds your [skills](https://www.aihero.dev/ai-coding-dictionary/skill), your [AGENTS.md](https://www.aihero.dev/ai-coding-dictionary/agents-md) and your shared docs. You run your [agent](https://www.aihero.dev/ai-coding-dictionary/agent) in the Home Repo. Its AGENTS.md holds a navigation pointer to each of your other repos, so the agent can open or clone them as it needs to.\n\n## [The problem it solves](#the-problem-it-solves)\n\nWhen a project spans several repos, an agent started in one of them sees only that repo. Each repo ends up with its own copy of the skills and the agent setup, and planning a feature that crosses repos means working without the whole overview.\n\nA Home Repo gives you:\n\n1. One place for your steering files and tooling\n2. One place to run all your agents\n3. Sweeping changes across multiple repos from a single [session](https://www.aihero.dev/ai-coding-dictionary/session)\n\n## [Set one up](#set-one-up)\n\nPaste this prompt into a new session with your coding agent, started in the folder that holds your repos. The agent finds your repos and their skills itself, [grills](https://www.aihero.dev/ai-coding-dictionary/grilling) you about the decisions in rounds, and changes nothing until you approve its plan.\n\n```\nSet up a Home Repo with me: one git repo that holds my shared skills,\nAGENTS.md and shared docs, and points at my other repos. I'll run my agent\nfrom it.\n\n## How to work\n\n- Look up every fact yourself (filesystem, git, gh), using subagents for\n  wide searches. Bring me only decisions.\n- Put decisions to me in rounds. Number each question, give your\n  recommended answer, and word it so \"yes\" accepts it. A question that\n  depends on one still open waits for a later round.\n- Until I approve the plan in Step 3, only read.\n- Secrets stay where they are: leave .env and other secret files unread.\n\n## Step 1: Inventory the repos\n\nFind every git repo under my home directory, skipping dependency folders.\nFor each, record its path, remote, visibility (public or private) and\nlast commit date.\n\nIn the first round, ask:\n- which repos the Home Repo points at (recommend those with recent commits)\n- where it lives, and whether it's new or an existing repo (recommend a\n  new private repo beside the others)\n- whether it's personal or shared with a team\n- which file my harness loads at session start: AGENTS.md, CLAUDE.md or\n  both (recommend what my setup shows)\n\nDone when every repo found is marked in or out, and the other three\nquestions are answered.\n\n## Step 2: Inventory the shared material\n\nAcross the chosen repos and my user-level skill folders (such as\n~/.claude/skills), list every skill (a folder with a SKILL.md), every\nAGENTS.md and CLAUDE.md, and every doc written for agents: coding\nstandards, glossaries, ADRs.\n\nSort each item into one bucket:\n- shared: true across repos\n- duplicate: the same item in several places; diff the copies and mark\n  the newest\n- repo-specific: about one repo's code, commands or domain\n- installed: from a published skills repo or marketplace\n\nDone when every item sits in exactly one bucket.\n\n## Step 3: Agree the plan\n\nShow a table of every item, where it is now, and its destination:\n- shared and duplicate: move to the Home Repo, one copy, newest version\n- repo-specific: stays in its repo\n- installed: stays installed\n\nUnder it, show the Home Repo's AGENTS.md: a short intro, then an\n\"Other Repos\" section with one pointer per repo:\n\n  <name> (<what it is>): <local path>. Clone from <remote> if missing.\n\nAdd a hint where a repo needs one, such as \"read its AGENTS.md first\".\nPast about 20 repos, group the pointers into one file per area and point\nat those files instead.\n\nSettle open items in further rounds. Done when I approve the table and\nthe AGENTS.md.\n\n## Step 4: Apply the plan\n\n1. Create the Home Repo and its AGENTS.md. If my harness loads a\n   different file, add that file as a one-line pointer to AGENTS.md.\n2. Copy each shared item in, keeping skill folders whole.\n3. In each child repo, on a new local branch, remove the copies that\n   moved. Repo-specific material stays.\n4. Commit in the Home Repo. Pushing is my call.\n\nDone when every row of the table is applied. Report each row's outcome,\nthe branches you created in each repo, and anything you skipped, with\nthe reason.\n```\n\n## [FAQ](#faq)\n\n### [Contents](#contents)\n\n**What goes in a Home Repo?**\nSkills you use across repos, AGENTS.md with its pointers, steering files, and shared docs such as coding standards, a glossary, and decisions that affect the whole system. Coding standards are the first doc worth sharing: one universal set transfers across projects. A Home Repo can also hold a small wiki of Markdown files, and tooling.\n\n**What stays in each repo?**\nAnything true of that repo alone: its own AGENTS.md, its build and test commands, its repo-specific docs. The Home Repo points at it. Code stays where it is, and each repo keeps its history, remote and issue tracker.\n\n**Why a repo, and not `~/.claude/skills`?**\nThe ideal end state is that everyone uses the same skills, kept in the project. A user folder is the stopgap until then. A Home Repo is a project: its skills are versioned with git, and a team can share it.\n\n**AGENTS.md or CLAUDE.md?**\nThis guide says AGENTS.md. Put the pointers in whichever file your harness loads at the start of a session. Claude Code loads CLAUDE.md.\n\n### [Navigation pointers](#navigation-pointers)\n\n**What does a pointer look like?**\nOne line per repo, naming the repo and where it lives:\n\n```\nFor skills, clone mattpocock/skills to ~/repos/skills.\nFor Sandcastle, clone mattpocock/sandcastle to ~/repos/sandcastle\n```\n\nAdd a hint where a repo needs one:\n\n```\n## Other Repos\n\nStorefront (Next.js app): ~/repos/acme/storefront. Clone from git@github.com:acme/storefront.git if missing.\nPayments API: ~/repos/acme/payments-api. Read its AGENTS.md before changing it.\nAI Hero: ~/repos/ai/ai-hero (git pull to view latest, likely out of date)\n```\n\n**Does the agent clone the repos, or use the copies already on disk?**\nBoth. If the repo is already at the pointer's path, the agent works there. If it isn't, the agent clones it there. Some setups clone the repos inside the Home Repo and gitignore them instead.\n\n### [Working across repos](#working-across-repos)\n\n**Where do sessions start?**\nIn the Home Repo, not inside a single repo. It's also the place to grill a feature that crosses repos.\n\n**How do worktrees fit in?**\nEach repo is cloned once. Each feature gets a worktree inside that clone, so several agents can work in one repo at the same time.\n\n**Where do issues go?**\nThe agent can reach every repo's issue tracker, so it can make sense of them together. Letting it file each issue where it fits works fine.\n\n**Can a team share a Home Repo?**\nYes. For a team, the Home Repo is the thing you share, and everyone runs their agents in it.\n\n### [Scale and alternatives](#scale-and-alternatives)\n\n**How many repos does it handle?**\nAbout 20 repos works fine. At around 400, one pointer per repo is too many decisions for the agent. Use [progressive disclosure](https://www.aihero.dev/ai-coding-dictionary/progressive-disclosure) instead: point at one file per area of the business, and list that area's repos in its file.\n\n```\n## Other Repos\n\nBilling (invoices, payments, tax): see repos/billing.md\nStorefront (web and mobile apps): see repos/storefront.md\nInternal tools: see repos/internal.md\n```\n\nAt thousands of repos, the skills have so many consumers that a skills marketplace makes more sense.\n\n**Should I use git submodules?**\nYou can. At 5-10 repos a submodules-style setup is fine. Plain pointers do the same job without submodules.\n\n**How does it relate to a monorepo?**\nA monorepo is a good fit when you can have one. A Home Repo replaces it when you can't, for example when you mix public and private repos, or when your team won't adopt a monorepo.\n\n### [Tooling and CI](#tooling-and-ci)\n\n**Do I need a CLI or other tooling?**\nNo. Pointers in AGENTS.md and the tools you already have are enough to start. Later, the Home Repo is a good place for tooling, such as a CLI that connects the agent to external services, with the environment variables it needs kept in the same repo.\n\n**Does it work in CI?**\nYes. In a [software factory](https://www.aihero.dev/ai-coding-dictionary/software-factory), put the Home Repo in the [sandbox](https://www.aihero.dev/ai-coding-dictionary/sandbox), and it clones the other repos as it needs them. The code that runs the factory lives in the Home Repo, or in one of the repos it points at.", "url": "https://wpnews.pro/news/the-home-repo-pattern", "canonical_source": "https://www.aihero.dev/the-home-repo-pattern", "published_at": "2026-11-12 11:17:27+00:00", "updated_at": "2026-11-12 11:21:16.619795+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["Home Repo", "AI Coding Dictionary"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/the-home-repo-pattern", "markdown": "https://wpnews.pro/news/the-home-repo-pattern.md", "text": "https://wpnews.pro/news/the-home-repo-pattern.txt", "jsonld": "https://wpnews.pro/news/the-home-repo-pattern.jsonld"}}