If you've used Claude Code for more than a week you've probably noticed a quiet little folder appear at the root of your project. It's called .claude, it's hidden by the dot, and most people never open it. That folder is the difference between Claude-as-chatbot and Claude-as-something-actually-shaped-to-your-work. Once you understand what's in there, the tool stops feeling generic and starts feeling like yours.

This is the tour I wish someone had given me on day one.

What's actually in .claude/

At the simplest level, .claude/ is a per-project configuration directory. It lives at the root of your repo, next to your package.json or pyproject.toml or whatever your stack uses. Claude Code looks for it automatically when you open a session in that folder, and it loads anything inside.

The pieces you actually care about:

• .claude/settings.json — the per-project config. Hooks, permissions, environment variables, MCP server registrations. This is where you tell the harness "always allow npm test" or "run this script after every Edit tool call."
• .claude/agents/ — one markdown file per subagent. These are the souls. Each file is a scoped character with its own system prompt, tool allowlist, and model choice. Claude's main thread can delegate to them.
• .claude/skills/ — one folder per skill. Each skill is a bundle of instructions plus optional scripts that Claude can invoke when the skill matches the task at hand.
• .claude/commands/ — slash commands. Each markdown file becomes a /your-command you can type at the prompt. These are great for repeated workflows you'd otherwise paste from a notes app.

There's a sibling concept too — a global ~/.claude/ in your home directory — that holds the same kinds of things but applies to every project you open. Personal skills, personal souls, your global hooks. Put project-specific things in the project's .claude/. Put cross-project habits in ~/.claude/. That's the only rule that matters about which folder to use.

Souls, in one paragraph

A soul is a markdown file in .claude/agents/. The frontmatter declares a name, a description (this is the part that decides whether the soul actually gets invoked — write it like a casting note, not a job posting), an optional tool allowlist, and an optional model choice. The body of the file is the system prompt. That's the whole thing. When the main Claude thread sees a task that matches your soul's description, it spins the soul up as a subagent, scoped to whatever tools you allowed, and lets it run to completion. Result comes back to the main thread. You don't pipe data around by hand.

I wrote a longer piece on adding souls if you want the ceremony in detail. The short version: one file, frontmatter on top, character on the bottom, save it, you're done.

Skills, in slightly more than one paragraph

Skills are the newer, larger sibling of souls. Where a soul is a who, a skill is a how. A skill is a folder under .claude/skills/ containing at minimum a SKILL.md file, and optionally any number of supporting scripts, reference files, templates, or examples. The SKILL.md has YAML frontmatter with a name and description (same casting-note rule applies — be specific about when the skill should fire), and a body that's a set of instructions Claude reads when the skill activates.

The trick that makes skills powerful is that they're loaded progressively. Claude doesn't pre-read every skill at session start — that would burn context. Instead, it reads the descriptions, decides which skills look relevant, and only then reads the full SKILL.md body and any referenced files. This means you can have dozens of skills installed without paying for them in your context window unless you actually need them.

A real example of when a skill beats a soul: I have a skill called commit that knows the conventions for my main project — when to use feat: vs chore:, how to format the body, what to do about co-author trailers, what files never to stage. When I tell Claude "commit this," the skill fires, the conventions get loaded, and the resulting commit looks like every other commit on the branch. No nagging. No re-explaining. The skill carries the institutional knowledge so I don't have to.

Souls are characters. Skills are playbooks. You'll end up wanting both.

How to add one of each, end to end

Let's actually wire something up. From the root of a project:

bashmkdir -p .claude/agents .claude/skills

Drop a soul in .claude/agents/duck.md:

markdown---
name: duck
description: Use when the user is stuck on a bug they've been staring at for more than ten minutes. A patient rubber duck that refuses to look at code and forces the user to explain what they think is happening, one assumption at a time. Never writes patches. Never runs edits. Asks dumb specific questions until the bug falls out.
tools: Read, Grep, Glob

You are a rubber duck. You do not write code. You do not suggest fixes.
Your only job is to ask the user to explain — out loud, in plain words —
what they think is happening, and to interrupt them every time they
gloss over an assumption with words like "obviously," "just," or "it
should." When they say "it should work," ask them what would have to be
true for that to be the case. Stay on it until the bug surfaces.

And a skill in .claude/skills/commit/SKILL.md:

markdown---
name: commit
description: Use when the user asks to commit changes. Stages relevant files, drafts a conventional-commits-style message in this project's house style, runs the project's pre-commit checks, and creates the commit. Never amends. Never force-pushes. Never stages credentials or .env files.

Commit skill
Follow these steps when the user asks you to commit:
1. Run git status and git diff to see what's actually changed.
2. Group the changes by intent. If they span multiple intents, ask the
   user whether to split them.
3. Draft a message in the form type(scope): subject where type is one
   of feat, fix, chore, refactor, docs, test, perf. Subject is lowercase,
   under 70 characters, no trailing period.
4. Stage the files explicitly by name. Never use git add -A or ..
5. Run the commit. If a hook fails, fix the issue and create a NEW
   commit — never amend.

That's it. Two files, two folders, and your project now has a debugging duck and a house-style commit assistant. Open Claude Code in the same directory and they're available immediately.

Where to find more (without writing them yourself)

This is the part I'm most excited about, because it's the part most people skip. You don't have to write souls and skills from scratch. There's a whole catalog of them on a-gnt — browse /categories/souls for characters and /categories/skills for playbooks. Filter by what you're actually trying to do. Pick one. Save it to your library. The file format is identical to what you'd write yourself, so installing a community soul is "copy file into .claude/agents/" and nothing else.

The catalog also has benches — pre-assembled bundles of MCP servers, souls, skills, and prompts wired together for a specific kind of work. A bench is the "starter pack" version of all this. If you don't know which souls and skills you need yet, browsing benches is the fastest way to find a working setup that someone else has already validated.

The mental model worth keeping

Think of .claude/ as the difference between renting a hotel room and moving into a house. Out of the box, Claude Code is the hotel room — clean, functional, identical for everyone. The .claude/ folder is where you start hanging pictures. You add a soul because you want a particular voice in your debugging sessions. You add a skill because you're tired of re-explaining the same workflow. You add a hook in settings.json because you want a check to run automatically every time a file gets edited. Each piece is small. The compounding effect is enormous.

Start with one soul and one skill this week. See what it feels like to open the project and have the assistant already know how you work. You'll start adding more before you've finished your first cup of coffee tomorrow.