The short version: Claude Code gives you two layers — project-level (.claude/ in the repo, shared with your team via git) and user-level (~/.claude/, follows you across projects) — plus plugins for anything you want to distribute. Put a thing in the narrowest layer that everyone who needs it can reach, give every skill a description that says when to use it, and keep one canonical copy of everything somewhere you can actually find it.

Here's the full system.

Know the two layers

Layer	Location	Travels with	Use for
Project	`.claude/` in the repo	the repo (git)	Conventions, project workflows, deploy steps, team skills
User	`~/.claude/`	your machine	Personal style, cross-project skills, your agent roster

The single most common mess is ignoring this split: personal preferences hardcoded into a repo's CLAUDE.md (now your teammates get your quirks), or project-critical workflows stashed in ~/.claude (now nobody else can run them, including you on your other machine).

Rule of thumb: if a new teammate cloning the repo would need it, it goes in the repo. If it's about you, it goes in ~/.claude.

Where each thing lives

your-repo/
├── CLAUDE.md                  # project conventions, commands, gotchas
├── .claude/
│   ├── skills/
│   │   └── deploy-check/
│   │       └── SKILL.md       # one skill = one folder + SKILL.md
│   ├── agents/
│   │   └── code-reviewer.md   # subagent definitions
│   └── settings.json          # shared permissions/config
└── .mcp.json                  # project-scoped MCP servers

~/.claude/
├── CLAUDE.md                  # your global preferences
├── skills/                    # skills available in every project
└── agents/                    # your personal agent roster

A skill is a folder with a SKILL.md whose frontmatter carries a name and a description. Slash commands are the same mechanism — typing /deploy-check invokes the skill by name.

The description is the trigger — write it like one

Claude decides whether to load a skill by reading its description, not its body. A description that names the trigger condition gets used; a vague one gets ignored:

# Gets used
description: Use when shipping a release — runs the pre-deploy
  checklist (build, env vars, migrations, smoke test).

# Gets ignored
description: Helpful deployment utilities.

The same discipline applies to agents: an agent definition that says when to dispatch it ("use for read-only codebase exploration when the answer spans many files") beats a title-only one.

Naming and scope conventions that hold up

One job per skill. fix-flaky-test and write-migration beat a utils skill with nine sections. Small skills load less context and trigger more precisely.
Kebab-case, verb-first names for anything invocable: review-pr, seed-staging, export-report. You'll be typing these as slash commands.
Keep CLAUDE.md for facts, skills for procedures. CLAUDE.md is loaded every session — conventions, commands, gotchas. Multi-step workflows belong in skills, which load only when needed.
Prompts you reuse are skills you haven't written yet. If you've pasted the same prompt three times, give it frontmatter and a name.

Versioning and portability

Project-level assets are solved by definition — they're in git, they ride your branches, they show up in code review like everything else.

User-level assets are where things rot. ~/.claude isn't in version control by default, doesn't follow you to a new machine, and silently drifts from the copies you pasted into other projects. Three ways to handle it, in ascending order of effort:

Git-init ~/.claude and push it to a private repo. Works, but merge conflicts between machines get old.
Package as plugins — if a set of skills/agents belongs together, a plugin makes it installable everywhere (see plugins vs skills vs MCP for when that's the right container).
Keep a canonical library outside any machine. This is what Vibe Coders' Kit is — agents, skills, prompt templates (with variables and version history), and MCP configs in one place, exportable to Claude Code, Cursor, VS Code, or Codex, and shareable via a public profile. Import a teammate's setup instead of screenshotting it from Slack.

We've written before about how much good work quietly dies in scattered gists and local files — stop losing your best Claude Code agents and skills covers the failure mode in detail.

A 30-minute cleanup that pays for itself

ls ~/.claude/skills and every project's .claude/ — inventory what exists.
Delete what you haven't used in a month. Dead skills still cost attention.
Move misplaced items across the project/user boundary (the rule of thumb above).
Rewrite the three descriptions you actually rely on so they name their trigger.
Put the survivors somewhere canonical — git, a plugin, or your toolkit.

Then stop reorganizing. The system above is boring on purpose — the point is to spend your attention on building, not on curating the meta-layer. For the broader workflow this slots into, see the Claude Code best practices guide.

FAQ

What's the difference between a skill and an agent? A skill is instructions loaded into the current conversation — a procedure Claude follows inline. An agent (subagent) is a separate Claude instance with its own context and tool permissions that you dispatch for a task. Skills teach; agents delegate.

Should CLAUDE.md be long? No. It's loaded every session, so every line taxes every conversation. Keep it to durable facts and conventions; push procedures into skills that load on demand.

How do teams share a common setup? Commit .claude/ and .mcp.json to the repo for project assets, and distribute cross-project assets as a plugin or through a shared template library like ours.