📋 context.md

Every agent that opens your project starts blind. context.md fixes that. It reads your codebase, asks only what code cannot answer, and writes a CLAUDE.md + AGENTS.md that gives any agent full orientation in a single read. Run /context-md-update to keep it fresh after every session.

Simple, minimal, lean. No templates to fill out. No config to maintain. Just run /context-md once and every agent you ever point at this repo starts knowing what it is, how to run it, and what never to touch.

Note

These skills have been built and tested with Claude Code. Codex support is experimental. If you try them on Codex, we'd love your help. Open an issue to share what works and what doesn't.

Quickstart

npx skills add -g amajorai/context.md

Then in Claude Code, from any project:

/context-md

To refresh after things change:

/context-md-update

To force-replace an existing context file:

/context-md overwrite

Update

npx skills update context-md

npx skills update context-md context-md-update

npx skills update

npx skills update -g -y

Claude Code plugin

/plugin marketplace add amajorai/context.md
/plugin install contextmd@amajorai

Invoke as /contextmd:context-md or /contextmd:context-md-update.

What gets written

/context-md produces a CLAUDE.md and AGENTS.md in your project root with these sections (only sections with real content are included):

Section	What it contains
Project name + description	1-2 sentences on what the project does and who uses it
Tech Stack	Language, framework, database, package manager, key libraries
Development	Install, run, test, build, lint commands
Directory Structure	Key directories with 1-line descriptions
Architecture	How the major pieces connect (skipped for simple projects)
Conventions	Naming rules, patterns, tooling decisions easy to get wrong
Environment	Required env vars without values (skipped if no .env found)
Agent Guidelines	Always/never rules specific to this codebase

Every file ends with a <!-- context.md last-updated: YYYY-MM-DD --> marker. /context-md-update reads this to know how far back to look for drift.

Works great with

• 👻 spec.md after /context-md - spec agents have full project context when breaking down tasks.
• 📦 ship.md - ship's explore phase starts from a solid foundation instead of rediscovering the codebase every run.
• 🪅 vibe.md - run /context-md after /vibe sets up your server to capture what was configured.
• 🎉 party.md - autonomous agents need up-to-date context to pick up issues without orientation overhead.
• 🔎 fix.md - debugging agents orient instantly instead of spending Phase 1 mapping the repo.
• 🎬 replay.md - agents know the app structure before recording flows.
• ⚡ amajorai/skills - all utility skills benefit from a workspace that already has context written.

Skills

Skill	What it does
/context-md	Initialize CLAUDE.md and AGENTS.md. Explores the codebase with parallel subagents, interviews for gaps, writes structured context files, and optionally adds a stop hook to remind you to update after each session.
/context-md-update	Refresh existing context files. Reads git log and package changes since the last update, interviews for anything new, and surgically updates only stale sections.

How it works

flowchart TD
    subgraph init["/context-md"]
        A["📂 Explore (4-5 parallel subagents)\nDirectory, packages, env, docs, source"] --> B{"Still open\nareas?"}
        B -->|"Yes"| C["🎤 Interview\nOne question at a time"]
        C --> A
        B -->|"No"| D["✍️ Write CLAUDE.md + AGENTS.md\nAll sections, structured for agent consumption"]
        D --> E["👁️ User review\nConfirm and tweak"]
        E --> F["🔔 Optional stop hook\nReminder to run /context-md-update each session"]
    end

    subgraph update["/context-md-update"]
        G["📖 Read existing files\nExtract last-updated date"] --> H["🔍 Detect drift\nGit log + package diff + dir scan"]
        H --> I["🎤 Interview\nAnything else changed?"]
        I --> J["✏️ Surgical update\nOnly stale sections, rest unchanged"]
        J --> K["👁️ User review\nDate stamp refreshed"]
    end

    F -.->|"after changes"| G

    style init fill:#1a1a2e,stroke:#4a4a8a
    style update fill:#1a1a2e,stroke:#4a4a8a

Loading

Auto-update hook

/context-md optionally adds a Claude Code stop hook that reminds you to run /context-md-update at the end of every session. You can also add it manually via /update-config or by editing .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Context may be stale. Run /context-md-update to refresh CLAUDE.md / AGENTS.md.'"
          }
        ]
      }
    ]
  }
}

Star History