Agent Context System quickstart: install and configure

Install the two-file context system, run init, and start your first agent session with persistent project knowledge — in under 5 minutes.

Getting Agent Context System running takes two steps: copy the files into your project, then run agent-context init. After that, every agent session starts with your project’s patterns, boundaries, and gotchas already loaded — no re-explaining required.

Choose your install method

GitHub Copilot (recommended)

Use the official Copilot skill registry. This installs the system as a managed skill and makes it easy to pull updates later.

npx skills add AndreaGriffiths11/agent-context-system
bash .agents/skills/agent-context-system/scripts/init-agent-context.sh

That’s it — the init script creates your files and wires up copilot-instructions.md automatically.

Manual / any agent

Copy only the files you need. Works with any agent: Claude Code, Cursor, Windsurf, OpenClaw, or any tool that reads an instruction file.

git clone https://github.com/AndreaGriffiths11/agent-context-system.git /tmp/acs
cp /tmp/acs/AGENTS.md /tmp/acs/agent-context ./
cp -r /tmp/acs/agent_docs /tmp/acs/scripts ./
rm -rf /tmp/acs
./agent-context init

OpenClaw

Clone directly into your skills directory. OpenClaw picks it up as a workspace skill on the next session.

git clone https://github.com/AndreaGriffiths11/agent-context-system.git skills/agent-context-system

Restart your OpenClaw session. It reads AGENTS.md automatically — no init step required.

New project from template

Start a brand-new repo from the GitHub template, then initialize.

gh repo create my-project --template AndreaGriffiths11/agent-context-system
cd my-project
./agent-context init

What init creates

After running agent-context init, your project will contain:

your-repo/
├── AGENTS.md                    # Committed. Always loaded. Under 120 lines.
├── .agents.local.md             # Gitignored. Personal scratchpad.
├── CLAUDE.md                    # Symlink → AGENTS.md (for Claude Code)
├── agent-context                # The CLI script
├── agent_docs/
│   ├── conventions.md           # Full code patterns and naming
│   ├── architecture.md          # System design and data flow
│   └── gotchas.md               # Extended known traps
└── scripts/
    └── init-agent-context.sh    # Wrapper for npx skills installs

init also adds .agents.local.md to your .gitignore so your personal scratchpad is never committed.

If you’re using Claude Code, init creates a CLAUDE.md symlink pointing to AGENTS.md. Claude doesn’t read AGENTS.md directly yet — the symlink bridges this automatically.

Set up your project context

1. Edit AGENTS.md

   Open AGENTS.md and replace the placeholder content with your actual project details. Fill in your project name, stack, package manager, build and test commands, and the real patterns and gotchas from your codebase.

   # Open AGENTS.md in your editor
   $EDITOR AGENTS.md
   

   Editing AGENTS.md is the highest-leverage action you can take after setup. Every line loads into every agent session. A well-filled AGENTS.md eliminates the most common “wrong answer” mistakes agents make on your specific codebase. Keep it under 120 lines — dense beats verbose.

2. Fill in agent_docs/

   Add deeper references to the agent_docs/ directory for content that doesn’t fit in AGENTS.md’s compressed format: full naming conventions, architecture decisions, extended gotcha explanations. Delete the templates that don’t apply to your project.

   agent_docs/
   ├── conventions.md   # Naming, file structure, code style
   ├── architecture.md  # System design, data flow, key decisions
   └── gotchas.md       # Extended traps with full explanations
   

   The agent loads these files on demand — only when a task requires more depth than AGENTS.md provides.

3. Customize .agents.local.md

   Open .agents.local.md and add your personal preferences: coding style, planning preferences, tone preferences. This file is gitignored and only affects your sessions.

   $EDITOR .agents.local.md
   
4. Verify your setup

   Run agent-context validate to confirm everything is in place before your first session.

   ./agent-context validate
   

   The validator checks that AGENTS.md exists and is under 120 lines, .agents.local.md is gitignored, and the CLAUDE.md symlink is wired up correctly.

5. Start working

   Open your agent tool and start a session. The agent reads both AGENTS.md and .agents.local.md at session start, applies your project knowledge, and logs learnings to the scratchpad at session end.

   For most agents (Copilot Chat, Cursor, Windsurf), prompt the agent to log the session when you’re done with meaningful work:

   Log this session to the scratchpad.
   

   Claude Code handles this automatically via its auto memory system.

6. Promote stable patterns

   Over time, your scratchpad accumulates session notes. When a pattern recurs across 3 or more sessions, the agent flags it in .agents.local.md under “Ready to Promote.” Run agent-context promote to review what’s been flagged.

   ./agent-context promote
   

   To auto-append all flagged patterns directly to AGENTS.md:

   ./agent-context promote --autopromote
   

   Review the changes, then commit AGENTS.md to share the promoted knowledge with your team.

CLI reference

All commands operate in the current working directory.

agent-context init              # Set up context system in current project
agent-context validate          # Check setup is correct
agent-context promote           # Find patterns to move from scratchpad to AGENTS.md
agent-context promote --autopromote  # Auto-append patterns recurring 3+ times

How knowledge flows

Once the system is running, knowledge follows a one-way promotion path:

Session notes → .agents.local.md → agent flags stable patterns → you promote to AGENTS.md
                    (personal)                                         (shared)

The scratchpad is where things are still experimental. AGENTS.md is where proven knowledge lives. The agent flags candidates — you make the call.

For a deeper look at the session logging lifecycle, compression, and auto-reflect observation mode, see how it works.