Project Setup Skill | Agent Skills

Project Setup

Set up projects to work optimally with Claude Code with proper configuration, permissions, and team sharing.

Quick Reference

| Directory/File | Purpose | Committed | |----------------|---------|-----------| | .claude/ | Project configuration root | Yes (mostly) | | .claude/settings.json | Project settings and hooks | Yes | | .claude/settings.local.json | Personal project overrides | No | | .claude/commands/ | Project slash commands | Yes | | .claude/skills/ | Project-specific skills | Yes | | CLAUDE.md | Project knowledge for Claude | Yes | | .mcp.json | Shared MCP servers | Yes | | ~/.claude/ | Personal global configuration | No |

Quick Setup Checklist

For new projects:

[ ] Create .claude/ directory structure
[ ] Add CLAUDE.md with project knowledge
[ ] Configure .claude/settings.json with permissions
[ ] Add .claude/settings.local.json to .gitignore
[ ] Set up MCP servers in .mcp.json if needed
[ ] Create project-specific slash commands
[ ] Run /init to verify setup

Directory Structure

Minimal Setup

project/
├── .claude/
│   └── settings.json          # Basic permissions
└── CLAUDE.md                  # Project knowledge

Standard Setup

project/
├── .claude/
│   ├── settings.json          # Shared project settings
│   ├── settings.local.json    # Personal overrides (gitignored)
│   ├── commands/              # Project slash commands
│   │   └── deploy.md
│   └── skills/                # Project-specific skills
│       └── domain-model/
│           └── SKILL.md
├── .mcp.json                  # Shared MCP servers
├── CLAUDE.md                  # Project knowledge (root)
└── src/
    └── CLAUDE.md              # Subdirectory knowledge (optional)

Full Setup (with hooks)

project/
├── .claude/
│   ├── settings.json          # Settings with hooks
│   ├── settings.local.json    # Personal overrides
│   ├── commands/              # Slash commands
│   │   ├── deploy.md
│   │   └── test.md
│   ├── skills/                # Project skills
│   │   └── domain-model/
│   │       └── SKILL.md
│   └── hooks/                 # Hook scripts
│       ├── format.sh
│       └── validate.py
├── .mcp.json                  # Shared MCP servers
└── CLAUDE.md                  # Project knowledge

CLAUDE.md

The most important file for Claude Code. Place in project root.

Template

# CLAUDE.md

## Project Overview
[Brief description of what this project does]

## Tech Stack
- [Framework/language]
- [Database]
- [Key dependencies]

## Commands
- `bun install` - Install dependencies
- `bun dev` - Start development server
- `bun test` - Run tests
- `bun build` - Build for production

## Architecture
[Key directories and their purposes]

## Code Style
- [Linting rules]
- [Naming conventions]
- [Patterns to follow]

## Important Notes
- [Gotchas and things Claude should know]

Location Precedence

Claude reads CLAUDE.md files in this order (all are included):

~/.claude/CLAUDE.md - Personal global instructions
~/CLAUDE.md - Home directory instructions
./CLAUDE.md - Project root
./src/CLAUDE.md - Subdirectory (and any other CLAUDE.md files)

Tip: Use subdirectory CLAUDE.md files for module-specific guidance.

Settings Files

.claude/settings.json

Project settings committed to version control.

{
  "permissions": {
    "allow": [
      "Bash(bun:*)",
      "Bash(git:*)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {}
}

.claude/settings.local.json

Personal overrides (add to .gitignore).

{
  "permissions": {
    "allow": [
      "Bash(docker:*)"
    ]
  },
  "env": {
    "DEBUG": "true"
  }
}

~/.claude/settings.json

User-level settings (applies to all projects).

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": []
  },
  "env": {}
}

Permission Setup

Permission Patterns

| Pattern | Matches | |---------|---------| | Read | All Read operations | | Bash(git:*) | All git commands | | Bash(npm install:*) | npm install with any args | | Bash(bun test src/**:*) | bun test on src directory | | Write(*.md) | Write to markdown files | | Edit(src/**) | Edit files in src/ |

Recommended Permissions by Project Type

Node.js/Bun:

{
  "permissions": {
    "allow": [
      "Bash(bun:*)", "Bash(npm:*)", "Bash(npx:*)",
      "Bash(git:*)",
      "Read", "Write", "Edit", "Glob", "Grep"
    ],
    "deny": [
      "Bash(rm -rf /*))",
      "Bash(sudo:*)"
    ]
  }
}

Python:

{
  "permissions": {
    "allow": [
      "Bash(python:*)", "Bash(pip:*)", "Bash(uv:*)",
      "Bash(pytest:*)",
      "Bash(git:*)",
      "Read", "Write", "Edit", "Glob", "Grep"
    ],
    "deny": [
      "Bash(rm -rf /*))",
      "Bash(sudo:*)"
    ]
  }
}

Rust:

{
  "permissions": {
    "allow": [
      "Bash(cargo:*)", "Bash(rustc:*)",
      "Bash(git:*)",
      "Read", "Write", "Edit", "Glob", "Grep"
    ],
    "deny": [
      "Bash(rm -rf /*))",
      "Bash(sudo:*)"
    ]
  }
}

MCP Server Configuration

.mcp.json (Shared)

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Adding Servers

# Add to project (creates .mcp.json)
claude mcp add --scope project memory -- npx -y @modelcontextprotocol/server-memory

# Add to user (all projects)
claude mcp add --scope user github -- npx -y @modelcontextprotocol/server-github

# Add remote server
claude mcp add --transport http context7 https://mcp.context7.com/v1/mcp

Hooks Setup

Add to .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Project: $(basename $CLAUDE_PROJECT_DIR)\""
          }
        ]
      }
    ]
  }
}

Team Considerations

What to Commit

| File | Commit? | Reason | |------|---------|--------| | .claude/settings.json | Yes | Shared project config | | .claude/settings.local.json | No | Personal overrides | | .claude/commands/ | Yes | Team slash commands | | .claude/skills/ | Yes | Team knowledge | | .claude/hooks/ | Yes | Shared automation | | .mcp.json | Yes | Shared MCP servers | | CLAUDE.md | Yes | Project knowledge |

.gitignore Additions

# Claude Code personal settings
.claude/settings.local.json
.claude/*.local.json

# MCP server data (if any)
.mcp-data/

Team Onboarding

Clone repository
Run /init to verify Claude Code setup
Create personal .claude/settings.local.json for overrides
Set required environment variables
Run /project-status (if command exists) to verify

Validation Commands

# Check Claude Code settings
claude config list

# Verify MCP servers
claude mcp list

# Check permissions
/permissions

# View hooks
/hooks

Common Issues

| Issue | Solution | |-------|----------| | Settings not loading | Check JSON syntax with jq . .claude/settings.json | | MCP server not starting | Run claude mcp logs <name> | | Permissions not applying | Check precedence: local > project > user | | CLAUDE.md not read | Ensure it's in project root or cwd | | Hooks not running | Verify script is executable |

Reference Files

| File | Contents | |------|----------| | CONFIGURATION.md | Deep dive into all configuration options | | PERMISSIONS.md | Permission patterns and security | | CHECKLIST.md | Complete setup and migration checklists |

Agent Skills: Project Setup

Skill Files