A Central Library for Your .claude Config

Ten repos on your machine. Every one of them carries a .claude folder stuffed with agents, skills, commands, hooks, plus a CLAUDE.md. A few stay current. Most started drifting weeks ago. The code review agent you fixed last month lives in one project, not the other nine. Your teammate shipped a planning command you have never seen because it sits only in their repo.

This is the .claude folder distribution problem. Add a project and it grows.

Quick Win: Stand up a private Git repo that holds your whole .claude content in one place, with a map.json that picks 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"]
    }
  }
}

One command runs the sync, and the .claude folder inside each project ends up matching its entry in the map. Tweak a skill or agent on site, send it back upstream, and every other project that references that item inherits the fix on its next sync.

Why .claude Folder Management Matters

Working in one codebase? Your skills, agents, and commands sit right beside the code. Every piece is in reach and every piece is current.

Cross five or six projects and things fall apart:

• Duplication everywhere. Eight repos each carry their own copy of git-commits, and no two are the same.
• Version drift. Last week's upgrade to the planning command only landed in a single repo. The rest still run the old code.
• No coordination. Your teammate built a database migration agent. You rolled your own because their version was invisible to you.
• Configuration sprawl. Skills are only the start. Hooks, settings.json, CLAUDE.md files, agent definitions, and slash commands all pile on. Every project wants a different combination.

Copying files is the first instinct. It feels fast and works for a moment, then falls over inside a month. Every engineer running agents across many repos lives this story.

IndyDevDan spotted this early and shipped a pure-agentic fix built around a YAML catalog full of references to external repos and paths. That approach proved the idea works. Running it across 10+ projects with 30+ skills and 19 agents surfaced the next need: stronger structure. Real file management. Variant support. Full coverage of the .claude folder. A sync engine that earns its keep.

The Library Architecture

The library is a private Git repo that holds the whole .claude configuration. Not pointers or references to other repos. The files themselves. One source of truth for each skill folder, each agent definition, each slash command, each hook, each CLAUDE.md, and each settings.json.

A map.json at the root says which project gets which items. A sync script copies the right files to the right spots. A manifest inside each project records what the library owns, so local files stay safe.

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 from a single repo. On a sync, the engine opens map.json, finds the project's entry, and copies exactly what the entry lists. Nothing extra, nothing missing.

The Map: Controlling What Goes Where

map.json is the brain. Every project entry spells out the items that project 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": {}
    }
  }
}

Another project can pick a totally different mix. A SaaS repo pulls in backend-engineer, supabase-specialist, and security-auditor agents together with postgres-best-practices and auth skills. A marketing-heavy repo trades those for growth-kit, seo-specialist, and content-writer. A product repo gets a leaner set with a different CLAUDE.md and different hooks. The library holds the whole catalog and every project chooses its own slice.

Profiles bundle shared configurations that several projects want to share:

{
  "profiles": {
    "web-default": {
      "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"],
      "hooks": ["SkillActivationHook", "Validators"]
    }
  }
}

Run --profile web-default when spinning up a new project and the full web stack lands in a single command.

Variants: When One Version Is Not Enough

Profiles leave a gap. Your git-commits skill runs fine in most repos, while the blog repo needs a tailored build that recognizes extra patterns tied to MDX writing. Splitting it into a brand-new skill is too heavy. What you actually want is the same skill wearing a per-project hat.

The naming pattern is name--variant, with a double dash between the base name and the variant tag:

skills/
├── git-commits/                    # Base version
│   └── SKILL.md
├── git-commits--blog/              # Variant for blog projects
│   ├── SKILL.md                    # Modified version
│   └── references/
│       └── mdx-patterns.md         # Extra file this variant needs

In map.json, the reference uses the full name:

{
  "skills": ["git-commits--blog", "react", "frontend-design"]
}

On sync, git-commits--blog drops into place at .claude/skills/git-commits/. The --blog suffix lives inside the library only. Nothing about it reaches the project. The variant is a self-contained folder. Different files, different structure, different content. The one thing it shares with the base is a deploy name.

Push is where the payoff lands. Edit .claude/skills/git-commits/ inside your blog project. During push, the engine cracks open the manifest, discovers that the local git-commits maps back to git-commits--blog, and routes the edits to that folder. Other projects keep pulling from the plain base.

Operations

The sync engine is a Node.js script with no external deps. Eight operations cover the full lifecycle:

Bootstrapping runs through seed. Aim it at any repo whose .claude folder is already in good shape, and the whole folder lands in the library. An entry gets added to map.json. A manifest gets written. From there on, canonical ownership lives in the library.

Content hashing powers the diff operation. It compares library and project versions and tags each item as in-sync, local-changes, or library-ahead, so drift becomes visible before any sync or push runs.

The Manifest: Tracking What the Library Owns

Every synced project gets a .claude/.library-manifest.json:

{
  "library_path": "/path/to/your-library",
  "synced_at": "2026-03-24T10:30:00Z",
  "library_commit": "abc123",
  "managed": {
    "skills": {
      "git-commits": "git-commits--blog",
      "react": "react",
      "frontend-design": "frontend-design"
    },
    "agents": {
      "frontend-specialist": "frontend-specialist"
    },
    "claude-md": "CLAUDE--web-full",
    "settings": "settings--web"
  }
}

Inside the manifest, each deploy name sits next to its library name. Push works against that mapping. A local git-commits/ folder flows back to git-commits--blog/ rather than overwriting the plain base.

Files that the manifest does not list are outside library view entirely. Personal notes, backups, one-off experiments inside .claude/ all ride through a sync without a scratch. Only the items the library placed are owned by the library.

Natural Language Interface

The system ships with more than a CLI. A /library slash command deploys into every synced project. Skip the flags and ask in plain English:

/library sync
/library I modified the blog command, push it back
/library add the payment-processing skill to this project
/library what's out of sync?
/library create a variant of react for this project
/library show me everything available

On the other side of the command, Claude opens the manifest, walks to the library, pulls out the intent from the sentence, and fires the sync engine. Anything destructive (deletes, overwrites) gets a confirmation prompt first.

That is the interaction model that makes the whole thing usable every day. The Claude Code session never has to close for library work. Speak the need out loud and the library reacts.

Getting Started

Building your own library takes about 30 minutes:

1. Create a private repo laid out with these folders: skills/, agents/, commands/, hooks/, claude-mds/, settings/

2. Seed from your best project. Pick whichever repo has the richest .claude folder today and pull its contents into the library. That bundle becomes the starting catalog.

3. Write your map.json. Begin with a single project record. For that record, spell out every item the project needs: each skill, each agent, each command, each hook, and any config file.

4. Build the sync script. The core stays simple. Load map.json. Parse item names, splitting on -- where variants appear. Copy files into their destinations. Write a manifest. Pull from Git before a sync. Commit and push after a push.

5. Add the /library command inside the library itself. Every synced project automatically picks it up, so plain-English control is available from the start.

6. Add a second project with a different mix. Two repos sharing one library is where the payoff shows. Same source, distinct configurations, drift-free on both sides.

One design call matters most: hold the real files in the repo, not pointers. Indirection adds a layer that turns variants into extra work and pushes into a knot. With the files sitting directly inside the library, syncing is copying, pushing is copying in reverse, and diffing is a hash check.

Why This Matters at Scale

Once the library is running, habits change. For reference, the working setup in this post covers 31 skills, 19 agents, 16 commands, 4 hook systems, and project-specific CLAUDE.md and settings.json files across 3 active projects. Here is how it plays in practice:

Improvements propagate. A bug fix in your code review agent goes in once. From the next sync onward, every project that lists that agent inherits the patch. No more hunting for the repo where a fix might live.

New projects start fast. Initialize a fresh repo with a profile and the whole agent team, hook bundle, settings, and CLAUDE.md land in seconds. Gone is the first-hour ritual of copying configuration files into place.

Variants prevent forking. A project that needs a tweaked version now takes a variant rather than drifting in silence. Base and variant relate to each other through an explicit link inside the library. Twelve months later, tracing which projects rely on which versions stays a one-query job.

The library self-distributes. The /library command lives in the library itself. Improve it and the upgrade rides along on the next sync into every project. The distribution system is distributed by itself.

The .claude folder distribution problem is a sign of a deeper shift. As agentic engineering grows up, your whole .claude configuration turns into real infrastructure: skills, agents, commands, hooks, rules, CLAUDE.md, and settings. They deserve the same care you give application code. One way to deliver it: a shared library, variant-aware, with sync that flows both directions.

For a head start on what a library can distribute, the ClaudeFast Code Kit ships 20+ production skills, 18 specialized agents (frontend-specialist, backend-engineer, security-auditor, quality-engineer, and more), a team orchestration system, and 5 production hooks ready to catalog and sync across your projects.

Frequently Asked Questions

What is a Claude Code library system?

One private Git repo that owns every piece of your .claude content in a single place: skills, agents, commands, hooks, CLAUDE.md files, and settings. map.json decides which items land in which project. A sync engine shuttles the right files into the right directories.

How is this different from IndyDevDan's the-library?

IndyDevDan's setup keeps references inside a YAML catalog, with pointers reaching out to GitHub repos or local paths. The pattern covered here stashes the real files directly inside one repo. A variant naming scheme supports per-project versions. A manifest enables bidirectional sync. Every .claude content category is in scope: skills, agents, commands, hooks, rules, CLAUDE.md, settings, and arbitrary files.

Does the library need to be open source?

No. A private repo is the right home. The library carries specialized skills, per-project CLAUDE.md files, and agent instructions that may be sensitive. Keep things private by default. A single skill you want to publish later can always get extracted into its own repo.

How do variants work?

A name--variant naming pattern is the core idea. A folder named react--strict/ inside the library lands at .claude/skills/react/ inside the project. Each variant is a standalone copy with its own files and layout. The manifest records the relationship so push operations carry edits back to the matching variant.

Can multiple people share one library?

Yes. Because it is a Git repo, a team clones it and pulls from it. Skill improvements go back on push. Every teammate picks those fixes up on their next sync. map.json can list entries covering everyone's projects.