Forge

What Gets Generated

# Project Name

## Overview
Brief description, purpose, key technologies.

## Architecture
Directory structure, key patterns, data flow.

## Key Files
Entry points, configuration, critical modules.

## Development
How to install, run, test, build, deploy.

## Conventions
Naming, file organization, coding patterns used.

## Important Context
Things Claude should know that aren't obvious from code.

AUTO-EXECUTE Protocol

When this skill is invoked:

1. Check for existing CLAUDE.md — if present, read it first
2. Scan the project root:
   • ls the top-level directory
   • Read package.json, pyproject.toml, Cargo.toml, or equivalent
   • Read README.md if present
   • Check for .env.example or .env.template
3. Scan source directories:
   • Glob for source files (**/*.py, **/*.ts, **/*.rs, etc.)
   • Read key entry points (main files, index files, app files)
   • Identify test directories and patterns
4. Scan configuration:
   • Build tools (webpack, vite, esbuild, cargo)
   • Linting (eslint, ruff, clippy)
   • CI/CD (GitHub Actions, GitLab CI)
   • Docker/containerization
5. Detect architecture patterns:
   • Look for common patterns (routes/, controllers/, models/, services/)
   • Identify state management, API patterns, database layers
6. Generate CLAUDE.md — write to project root
7. Report findings — summarize what was discovered

When to Use

• Opening a project for the first time
• Joining a new team or codebase
• A project has no CLAUDE.md and Claude keeps making wrong assumptions
• After major refactoring that changed project structure
• When Claude says "I'm not sure about the architecture"

Safety

• FORGE will never overwrite an existing CLAUDE.md without asking first
• If a CLAUDE.md exists, FORGE reads it and offers to update (not replace)
• FORGE only reads files — it does not execute any code from the project

Prerequisites

• Claude Code with file read/write access
• A project directory with source code to scan
• No external packages required

Quality Checklist

A properly forged CLAUDE.md should:

• Accurately describe the project's purpose
• List all major dependencies and their roles
• Map the directory structure with explanations
• Document how to install, run, test, and build
• Identify naming conventions and coding patterns
• Note any non-obvious architecture decisions
• Be concise enough to fit in context without waste

Tips

• Run /forge check periodically to verify the CLAUDE.md is still accurate
• After major changes, run /forge update instead of a full re-forge
• FORGE reads your code — it doesn't execute it. Safe to run on any project.
• The generated CLAUDE.md is a starting point. Edit it to add context only you know.

Know the codebase. Then write the code.