Project Structure

What ContextForge creates inside your repo, and why it's structured this way.

Full structure after init

txt

project/
  AGENTS.md              ← tiny pointer file for Codex / general agents
  CLAUDE.md              ← tiny pointer file for Claude Code (if selected)

  .contextforge/
    config.json          ← desired state
    lock.json            ← resolved installed state

    agents/
      codex/
        verification-before-completion.md
        nextjs-best-practices.md

      claude/
        verification-before-completion.md
        nextjs-best-practices.md

      cursor/
        verification-before-completion.md

      copilot/
        verification-before-completion.md

    skills/
      verification-before-completion/
        SKILL.md

      nextjs-best-practices/
        SKILL.md

agents/ vs skills/

.contextforge/agents/<tool>/ contains tool-specific adapted instructions. Each AI tool gets its own folder. Codex instructions are worded differently from Claude Code instructions, even for the same pack.

.contextforge/skills/<pack>/SKILL.md contains the full skill reference for each pack — the canonical, tool-neutral version that agents can consult for detail.

Root pointer files

Root files are tiny by design. They tell the agent where to look — they don't contain the instructions themselves.

AGENTS.md

# Project Agent Instructions

<!-- contextforge:start -->

ContextForge is installed for this repo.

Before working, read the relevant instruction files in:

- `.contextforge/agents/codex/`
- `.contextforge/skills/`

Follow the installed packs listed in `.contextforge/config.json`.
Do not copy these instructions into this file.

<!-- contextforge:end -->

CLAUDE.md

# Claude Code Instructions

<!-- contextforge:start -->

ContextForge is installed for this repo.

Before working, read the relevant instruction files in:

- `.contextforge/agents/claude/`
- `.contextforge/skills/`

Follow the installed packs listed in `.contextforge/config.json`.
Do not copy these instructions into this file.

<!-- contextforge:end -->

Why keep root files tiny?

→Root files accumulate many things over time. Keeping them clean reduces noise.
→Real content in .contextforge/ can be updated or replaced by sync without touching your root files.
→Different tools get different adapted instructions without polluting a single file.
→You can audit exactly what instructions each tool receives.

Next: CLI Commands