Claude Code frameworksCLAUDE.md, skills, hooks, and slash commands

What Claude Code frameworks are

Claude Code is stateless by default. Each session starts fresh. It reads your code, but it does not remember your preferences, your team's conventions, or how you deploy.

A framework fixes that. It is a set of files, checked into your repo, that give Claude persistent context:

These four pieces work together. CLAUDE.md sets the rules. Skills provide deep knowledge. Hooks enforce quality gates. Slash commands accelerate common tasks.

Because everything lives in your repo, the framework travels with your code. Clone the repo, open Claude Code, and you get the full context immediately. No setup docs. No onboarding calls.

How CLAUDE.md works

CLAUDE.md is a markdown file in your project root. Claude Code reads it at the start of every session. Whatever you put in this file becomes part of Claude's system context.

There are three levels, each with different scope:

The project-level file is the most important. It is version-controlled and shared with your team. Here is a real example:

# Project: Acme SaaS Platform

## Tech stack
- Next.js 15 (App Router, Server Components)
- TypeScript strict mode
- Tailwind CSS 4 (CSS-first config, no tailwind.config.ts)
- Supabase (PostgreSQL, Auth, RLS)
- Stripe for billing

## Critical rules
1. Always `await params` in page components (Next.js 15)
2. Never modify payment/auth code without approval
3. Use server components by default. Client components only for interactivity
4. All database queries go through `src/lib/db/`, never raw SQL in components

## File structure
- `src/app/` - Pages (App Router)
- `src/components/` - Shared components
- `src/lib/` - Business logic, utilities
- `src/types/` - TypeScript types (auto-generated from Supabase)

## Testing
- Run `npm run typecheck` before committing
- Integration tests in `__tests__/` use Vitest
- Never mock Supabase client. Use the test project instead

## Deployment
- Push to main triggers Vercel deploy
- Preview deployments on PRs
- Environment variables are in Vercel, never in .env files in the repo

What to put in CLAUDE.md

Focus on things Claude cannot infer from your code:

• Why decisions were made. "We use server components because our pages are SEO-critical."
• Safety boundaries. Files or systems Claude should never touch without asking.
• Non-obvious patterns. "This project uses Zod v4 where z.record() requires two arguments."
• Build and deploy steps. How to verify changes actually work.
• External service context. Which APIs you use, rate limits, auth patterns.

What not to put in CLAUDE.md

• Generic coding advice. Claude already knows how to write TypeScript.
• Secrets or credentials. Use environment variables.
• Entire API docs. Use skills for that (covered next).
• Long prose. Keep it scannable. Bullet points and code blocks work best.

The skills system

Skills are reusable knowledge modules. Each skill is a markdown file that teaches Claude a specific capability. Unlike CLAUDE.md (which loads every session), skills load on demand when referenced.

Skill structure

A skill lives in a directory with a SKILL.md file:

your-project/
  .claude/
    skills/
      api-design/
        SKILL.md          # Skill instructions
        examples/         # Reference files
          rest-endpoint.ts
          graphql-schema.ts
      database-migrations/
        SKILL.md
      code-review/
        SKILL.md

Writing a skill

A skill file is plain markdown. It should be specific and actionable. Here is an example:

# API design skill

## When to use
Invoke this skill when creating or modifying API routes.

## Standards
- All routes use the App Router pattern: `src/app/api/[resource]/route.ts`
- Validate request bodies with Zod schemas from `src/lib/validation/`
- Return consistent JSON: `{ data, error, meta }`
- Use `NextResponse.json()` with explicit status codes
- Rate limit public endpoints with `src/lib/rate-limit.ts`

## Error handling pattern
```typescript
import { validateBody } from '@/lib/validation'
import { rateLimiter } from '@/lib/rate-limit'

export async function POST(request: Request) {
  const limited = await rateLimiter.check(request)
  if (limited) return limited

  const body = await validateBody(request, createUserSchema)
  if (body instanceof NextResponse) return body

  try {
    const result = await createUser(body)
    return NextResponse.json({ data: result }, { status: 201 })
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to create user' },
      { status: 500 }
    )
  }
}
```

## Naming conventions
- Resource routes: `/api/users`, `/api/projects`
- Action routes: `/api/users/[id]/activate`
- Never nest more than 3 levels deep

Installing community skills

You can install skills from the community using the claude skill add command. Skills get cloned into your project's .claude/skills/ directory.

# Install a skill from a GitHub repo
claude skill add github:acme/claude-skills/nextjs-patterns

# Install from a URL
claude skill add https://example.com/skills/typescript-strict

# List installed skills
claude skill list

Hooks: automated tool events

Hooks let you run shell commands when Claude performs specific actions. They execute in your local environment, not inside Claude. This means you can enforce linting, run tests, validate schemas, or trigger any CLI tool automatically.

Hook types

Hooks are defined in .claude/settings.json under the hooks key:

Hook configuration

Here is a practical hooks configuration that auto-lints TypeScript files after every edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      },
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf /' && echo 'BLOCK: dangerous command' && exit 1 || true"
      }
    ],
    "Stop": [
      {
        "command": "npm run typecheck 2>&1 | tail -5"
      }
    ]
  }
}

How hooks execute

• Hooks run in your shell, not in Claude's sandbox. They have full access to your system.
• Environment variables like $CLAUDE_FILE_PATH provide context about what Claude just did.
• If a PreToolUse hook exits with code 1, the tool call is blocked.
• Hook output is shown to Claude, so it can react to linting errors or test failures.
• The matcher field filters which tools trigger the hook. Use | to match multiple tools.

Slash commands: custom workflows

Slash commands let you define multi-step workflows that trigger with a single /command. They are markdown files that contain prompts for Claude to follow.

Creating a slash command

Slash commands live in .claude/commands/. The filename becomes the command name:

.claude/
  commands/
    review.md        # Triggered by /review
    deploy.md        # Triggered by /deploy
    new-feature.md   # Triggered by /new-feature
    db-migrate.md    # Triggered by /db-migrate

Each file contains the prompt Claude should follow. Here is a code review command:

Review the current git diff for:

1. **Security issues**: SQL injection, XSS, exposed secrets, auth bypasses
2. **Performance**: N+1 queries, missing indexes, unnecessary re-renders
3. **Type safety**: Any `any` types, missing null checks, unsafe casts
4. **Consistency**: Does this follow the patterns in CLAUDE.md?

For each issue found:
- State the file and line
- Explain the risk
- Suggest a fix

If no issues found, say so. Do not invent problems.

Run: `git diff --staged` to see what is being committed.

And a deployment command:

Pre-deployment checklist:

1. Run `npm run typecheck` and fix any errors
2. Run `npm run build` and verify it passes
3. Run `npm run test` and verify all tests pass
4. Check `git status` for uncommitted changes
5. If all checks pass, run `git push origin main`

Report the result of each step. Stop immediately if any step fails.
Do not push if there are failures.

Using slash commands

Type the command in Claude Code's input. Claude reads the markdown file and executes the workflow. You can pass arguments after the command name, and they are available via the $ARGUMENTS variable in the prompt.

> /review
> /deploy
> /new-feature user authentication with OAuth

Building a complete framework for your team

A good framework has four layers. Start with CLAUDE.md and add the others as your team identifies repetitive patterns.

Step 1: define coding standards in CLAUDE.md

Start with the rules your team already follows. Pull from your existing code review checklists, style guides, and architecture decision records.

• Tech stack and version requirements
• File naming and directory structure
• Error handling patterns
• Testing requirements
• Safety boundaries (what not to touch)

Step 2: add domain-specific skills

Identify areas where Claude needs deep context that would bloat CLAUDE.md. Common skill areas:

• API design patterns with examples from your codebase
• Database migration procedures
• Third-party integration guides (Stripe, Supabase, etc.)
• Writing voice and brand guidelines
• Infrastructure and deployment processes

Step 3: configure hooks for quality gates

Hooks catch issues before they reach your PR. Recommended setup:

PostToolUse (Edit/Write):
  - ESLint --fix on changed files
  - Prettier --write on changed files

PreToolUse (Bash):
  - Block destructive git commands (force push, reset --hard)
  - Block commands that modify production resources

Stop:
  - Run typecheck
  - Run affected tests

Step 4: create slash commands for common workflows

Look at your team's most common tasks. If someone does the same 5-step process weekly, make it a slash command.

• /review for pre-commit code review
• /deploy for deployment checklists
• /new-feature for scaffolding new features
• /db-migrate for database migration workflows
• /debug for structured debugging sessions

Real examples

Three complete frameworks for different project types. Each one is production-tested.

# Directory structure
.claude/
  settings.json          # Hooks config
  commands/
    review.md            # /review - pre-commit review
    deploy.md            # /deploy - deployment checklist
    new-page.md          # /new-page - scaffold App Router page
    db-migrate.md        # /db-migrate - Supabase migration flow
  skills/
    api-design/SKILL.md  # REST API patterns
    auth/SKILL.md        # Auth + RLS patterns
    components/SKILL.md  # React component patterns
CLAUDE.md                # Project rules

# CLAUDE.md highlights
- Next.js 15 with App Router. Always await params
- Supabase with Row Level Security on every table
- Server components by default
- All API routes validate with Zod schemas
- Never modify: auth flows, payment code, RLS policies
- Build must pass before every commit

# Hooks
PostToolUse (Edit/Write): eslint --fix + prettier
Stop: npm run typecheck

# Directory structure
.claude/
  settings.json
  commands/
    test-pipeline.md     # /test-pipeline - run with sample data
    add-source.md        # /add-source - scaffold new data source
    validate-schema.md   # /validate-schema - check output schemas
  skills/
    dbt/SKILL.md         # dbt model patterns
    airflow/SKILL.md     # DAG authoring patterns
    data-quality/SKILL.md # Great Expectations setup
CLAUDE.md

# CLAUDE.md highlights
- Python 3.12, uv for package management
- Type hints required on all functions
- All pipelines use the Pipeline base class in src/core/
- Data validation with Pydantic models
- Tests use pytest with fixtures in conftest.py
- Never write raw SQL. Use SQLAlchemy models
- All secrets come from AWS Secrets Manager

# Hooks
PostToolUse (Edit/Write): ruff check --fix + ruff format
Stop: pytest tests/ -x --tb=short

# Directory structure
.claude/
  settings.json
  commands/
    plan.md              # /plan - terraform plan + review
    apply.md             # /apply - terraform apply with checks
    rollback.md          # /rollback - revert last deployment
    audit.md             # /audit - security scan all configs
  skills/
    terraform/SKILL.md   # Module patterns, state management
    k8s/SKILL.md         # Kubernetes manifests, Helm charts
    ci-cd/SKILL.md       # GitHub Actions patterns
CLAUDE.md

# CLAUDE.md highlights
- Terraform 1.8+ with OpenTofu compatibility
- All infrastructure changes go through PR review
- Kubernetes manifests in k8s/ use Kustomize overlays
- Never modify production state directly
- Never run terraform apply without terraform plan first
- All secrets in HashiCorp Vault, never in tfvars
- Tag every resource with: team, environment, cost-center

# Hooks
PreToolUse (Bash): Block "terraform apply" without prior plan
PostToolUse (Edit/Write): terraform fmt + tflint
Stop: terraform validate

Tips for effective frameworks