What Is the Perfect Claude Folder Structure for Any Project?

Why Folder Structure Matters

Claude Code reads your .claude folder on every session. The files and folders you put there determine what Claude knows, what it can do, and how it behaves on this specific project.

Most people ignore this. They use Claude without any project-specific configuration. That's like hiring a contractor and refusing to tell them anything about your business. Technically possible. Wildly inefficient.

The right folder structure takes 30 minutes to set up and pays dividends forever.

The Complete Structure

Here's the file layout that works for basically any project:

my-project/
├── CLAUDE.md          (project memory)
└── .claude/
    ├── settings.json  (configuration)
    ├── commands/      (slash commands)
    ├── hooks/         (event triggers)
    ├── skills/        (repeatable capabilities)
    └── agents/        (autonomous workers)

CLAUDE.md: Your Project's Brain

CLAUDE.md sits at the root of your project. Not inside .claude. At the top level where Claude sees it immediately.

This file tells Claude everything it needs to know about this specific project: what the project does, who the user is, what conventions to follow, what decisions have been made, what patterns to respect.

A good CLAUDE.md has sections for: project purpose, tech stack, code conventions, domain-specific terminology, decisions and rationale, things to never do.

Write this like you're briefing a senior contractor who's brilliant but has never seen your project. The better your CLAUDE.md, the less time you waste re-explaining things.

settings.json: Configuration

settings.json controls how Claude behaves on this project. Model selection. Permissions. Default tools. Everything that configures Claude's operation rather than its knowledge.

For most projects, you don't need to customize settings.json much. Defaults work for most use cases. But it's the place to change things when you need to.

Common customizations: restricting which tools Claude can use in sensitive projects, setting specific models for different tasks, configuring whether Claude should auto-format code or ask first.

commands/: Slash Commands

Commands are custom slash commands you can invoke in Claude. Each command is a simple file that defines what happens when you type /command-name.

Common commands: /deploy to trigger deployment, /test to run test suites, /commit to generate a commit message from current changes, /review to get Claude to review your work.

Commands are for things you do frequently and want a shortcut for. They're not for complex logic. Keep them simple. Use skills for anything complex.

hooks/: Event Triggers

Hooks are scripts that run when specific events happen. Pre-commit hooks run before Claude commits changes. Post-file-save hooks run after files are saved. Pre-push hooks run before Claude pushes to a remote repo.

Use hooks for automation that should happen invisibly. Enforcing code standards. Running linters. Checking for security issues. Anything that should happen automatically without cluttering Claude's primary interactions.

Well-configured hooks are where security and quality enforcement live. Bad hooks slow everything down. Good hooks are invisible and indispensable.

skills/: Where the Real Power Lives

Skills are the folder that actually transforms your productivity. Each skill is a sub-folder with a SKILL.md file that describes a repeatable process.

Examples of skills worth having in most projects:

• blog-write/: Your blog writing process with brand voice and formatting standards.
• review-pr/: Your code review checklist and standards.
• deploy/: Your deployment process with proper checks and rollback capability.
• weekly-report/: Your weekly reporting format and data sources.
• customer-email/: Your customer communication templates and escalation paths.

Each skill is a folder plus a SKILL.md. No configuration needed. Claude discovers skills automatically.

The rule: if you do something more than twice, turn it into a skill. Over time, this folder becomes your team's institutional knowledge in executable form.

agents/: Autonomous Workers

The agents folder contains definitions for autonomous workers. Each agent has specific responsibilities and runs on triggers (schedule, events, or manual).

Agents differ from skills in autonomy. A skill is a process Claude executes when invoked. An agent is a worker that runs on its own and decides when to do things.

Example agents: a sales agent that monitors your CRM, a content agent that watches for relevant news, a support agent that handles tier-1 questions, a monitoring agent that watches your systems.

Most projects don't need agents on day one. Start with skills. Graduate to agents when specific patterns of work justify autonomous operation.

The One-File-Per-Concern Rule

As your project grows, resist the temptation to dump everything in one place.

Bad: a single skills/everything.md file with fifteen different processes.

Good: fifteen separate skill folders, each focused on one specific capability.

The separation makes skills discoverable, reusable, and independently improvable. You can update one skill without affecting others. You can see at a glance what capabilities exist.

Don't Guess: Write Your Rules

The biggest mistake people make with the .claude folder is leaving things implicit.

You have coding standards. You have deployment procedures. You have naming conventions. Write them down in your CLAUDE.md and skill files. Don't assume Claude will guess them correctly.

This is the work most people skip. And it's why Claude feels generic to most users but feels like a team member to the users who do the work.

Getting Started

Create your .claude folder structure in your main project this week:

1. Write a CLAUDE.md that genuinely describes your project.
2. Create settings.json with default configuration.
3. Add your first skill. Pick something you do repeatedly.
4. Add your first command. Something you type often.

Don't try to build the full structure all at once. Add things as you realize you need them. Within a few weeks, your .claude folder becomes invaluable.

Your AI is only as good as the instructions you give it. Give it good instructions.