blog

Build a central library to manage .claude folders across projects. One repo for skills, agents, commands, hooks, and configs.

<!-- truncate -->

You have 10 codebases. Each one has a `.claude` folder with skills, agents, commands, hooks, and a CLAUDE.md file. Some folders are current. Most drifted weeks ago. You improved your code review agent in one project and forgot to copy it to the other nine. Your teammate built a planning command you never knew existed because it lives in their repo, not yours.

This is the `.claude` folder distribution problem. It gets worse with every project you add.

**Quick Win**: Build a private Git repo that holds all your `.claude` content centrally, with a `map.json` that controls which project gets which items:

```
{
  "projects": {
    "~/projects/webapp": {
      "claude-md": "web-full",
      "skills": ["git-commits", "react", "frontend-design"],
      "agents": ["visual-explainer"],
      "commands": ["team-plan", "build"]
    }
  }
}
```

Run one sync command and the project's `.claude` folder matches the map. Modify a skill or agent locally, push it back to the library, and every project that uses it picks up the change on next sync.

## Why .claude Folder Management Matters

If you work in a single codebase, your skills, agents, and commands live right next to your code. Everything is findable, everything is current.

Once you pass five or six projects, things break down:

- **Duplication everywhere.** The same git-commits skill exists in 8 repos, each slightly different.
- **Version drift.** You improved your planning command last week, but only in one project. The other repos still run the old version.
- **No coordination.** Your teammate built a database migration agent. You built your own because you didn't know theirs existed.
- **Configuration sprawl.** It's not just skills. It's hooks, settings.json, CLAUDE.md files, agent definitions, and slash commands. Each project needs a different combination.

The instinct is to copy files. It's fast, it works in the moment, and it falls apart within a month. Every engineer running multi-repo agent setups has been there.

[IndyDevDan](https://github.com/disler/the-library) identified this problem early and built a pure-agentic solution using a YAML catalog of references. His approach proved the pattern works. But after adopting it across 10+ projects with 30+ skills and 19 agents, I needed something with more structure: actual file management, variant support, full `.claude` folder coverage, and a real sync engine.

## The Library Architecture

The library is a private Git repo that stores your complete `.claude` configuration. Not references or pointers to other repos. The actual files. One canonical copy of every skill folder, every agent definition, every slash command, every hook, every CLAUDE.md, and every settings.json.

A `map.json` at the root defines which project gets which items. A sync script copies the right files to the right places. A manifest in each project tracks what the library owns so local files are never touched.

```
your-library/
├── map.json                    # Which projects get what
├── sync.mjs                    # Node.js sync engine
│
├── skills/                     # All skill folders
│   ├── git-commits/
│   ├── agentic-builder/
│   ├── react/
│   ├── growth-kit/
│   ├── session-management/
│   └── ... (31 skills in my library)
│
├── agents/                     # All agent .md files
│   ├── frontend-specialist.md
│   ├── backend-engineer.md
│   ├── security-auditor.md
│   ├── master-orchestrator.md
│   └── ... (19 agents in my library)
│
├── commands/                   # All slash commands
│   ├── team-plan.md
│   ├── build.md
│   ├── team-build.md
│   └── ... (16 commands in my library)
│
├── hooks/                      # All hook folders
│   ├── SkillActivationHook/
│   ├── ContextRecoveryHook/
│   └── Validators/
│
├── claude-mds/                 # CLAUDE.md variants (full replacement per project)
│   ├── CLAUDE--web-full.md
│   └── CLAUDE--product.md
│
├── settings/                   # settings.json variants
│   ├── settings--web.json
│   └── settings--product.json
│
└── rules/                      # .claude/rules/ files
    ├── repo-primer--webapp.md
    └── repo-primer--product.md
```

Eight content categories (skills, agents, commands, hooks, rules, claude-mds, settings, and arbitrary files), all managed through one repo. When you sync a project, the engine reads `map.json`, finds the project's configuration, and copies exactly the items listed. Nothing more, nothing less.

## The Map: Controlling What Goes Where

The `map.json` is the brain of the system. Each project entry lists exactly which items it receives:

```
{
  "$schema": "library-map-v1",
  "projects": {
    "C:/Github/my-webapp": {
      "claude-md": "CLAUDE--web-full",
      "settings": "settings--web",
      "skills": [
        "git-commits",
        "react",
        "frontend-design",
        "session-management"
      ],
      "agents": ["frontend-specialist", "quality-engineer"],
      "commands": ["team-plan", "build", "team-build"],
      "hooks": ["SkillActivationHook", "Validators"],
      "rules": [],
      "files": {}
    }
  }
}
```

A different project might use a completely different selection. A SaaS project gets `backend-engineer`, `supabase-specialist`, and `security-auditor` agents with `postgres-best-practices` and `auth` skills. A marketing-focused repo gets `growth-kit`, `seo-specialist`, and `content-writer` instead. A product repo gets a stripped-down set with a different [CLAUDE.md](/blog/claude-md-mastery) and different hooks. The library holds everything; each project picks what it needs.

You can also define **profiles** for common configurations that multiple projects share:

```
{
  "profiles": {
    "web-default": {
      "claude-md": "CLAUDE--web-full",
      "settings": "settings--web",
      "skills": [
        "git-commits",
        "react",
        "frontend-de