> ## Documentation Index
> Fetch the complete documentation index at: https://mainbranch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Agent Context System in any project manually

> Three ways to install Agent Context System: copy files into an existing project, create from the GitHub template, or clone as an OpenClaw workspace skill.

The Agent Context System is a set of files — no package manager or plugin required. You can add it to any project by copying the files directly, start a new project from the GitHub template, or install it as an OpenClaw workspace skill. All three approaches give you the same two-file system: `AGENTS.md` for committed project knowledge and `.agents.local.md` for your personal scratchpad.

## Choose your install method

<Tabs>
  <Tab title="Existing project">
    Copy the Agent Context System files into a project you already have.

    <Steps>
      <Step title="Clone and copy the files">
        Run the following from your project root:

        ```bash theme={null}
        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
        ```

        This copies `AGENTS.md`, the `agent-context` CLI, the `agent_docs/` reference directory, and the `scripts/` directory into your project root, then removes the temporary clone.
      </Step>

      <Step title="Run init">
        ```bash theme={null}
        ./agent-context init
        ```

        The init command creates `.agents.local.md` from the template, adds it to `.gitignore`, and asks which agent tools you use. It then creates the appropriate config file for each tool you select.
      </Step>

      <Step title="Edit AGENTS.md">
        Open `AGENTS.md` and replace the placeholder content with real information about your project: name, stack, commands, patterns, boundaries, and gotchas. This is the highest-leverage edit you will make.
      </Step>
    </Steps>
  </Tab>

  <Tab title="New template project">
    Create a new repository directly from the Agent Context System template on GitHub.

    <Steps>
      <Step title="Create the repository from the template">
        ```bash theme={null}
        gh repo create my-project --template AndreaGriffiths11/agent-context-system
        cd my-project
        ```

        Replace `my-project` with your repository name. This creates a new GitHub repository with all the Agent Context System files already in place.
      </Step>

      <Step title="Run init">
        ```bash theme={null}
        ./agent-context init
        ```

        Init sets up `.agents.local.md`, wires up the agent tool configs for whichever tools you select, and ensures the scratchpad is gitignored.
      </Step>

      <Step title="Edit AGENTS.md">
        Open `AGENTS.md` and fill in your project-specific details. The template contains placeholder content — replace it with what is actually true about your project.
      </Step>
    </Steps>

    <Tip>
      Starting from the template is the fastest path to a working setup. You get `AGENTS.md`, the `agent-context` CLI, all scripts, and the `agent_docs/` directory structure in one step.
    </Tip>
  </Tab>

  <Tab title="OpenClaw">
    OpenClaw reads workspace skills directly from a `skills/` directory. No init command is needed.

    <Steps>
      <Step title="Clone into your skills directory">
        From your project root:

        ```bash theme={null}
        git clone https://github.com/AndreaGriffiths11/agent-context-system.git skills/agent-context-system
        ```
      </Step>

      <Step title="Restart your OpenClaw session">
        OpenClaw picks up workspace skills on session start. Restart your session after cloning, and OpenClaw will read `AGENTS.md` automatically.
      </Step>

      <Step title="Edit AGENTS.md">
        Open `skills/agent-context-system/AGENTS.md` and fill in your project specifics.
      </Step>
    </Steps>

    <Note>
      Unlike the other install methods, OpenClaw does not require running `./agent-context init`. OpenClaw's skill system handles loading the context automatically.
    </Note>
  </Tab>
</Tabs>

## What init creates

After running `./agent-context init`, your project will contain the following files:

| File                              | Purpose                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------ |
| `AGENTS.md`                       | Committed project knowledge. Always loaded. Keep under 120 lines.              |
| `.agents.local.md`                | Gitignored personal scratchpad. Grows as the agent logs session learnings.     |
| `CLAUDE.md`                       | Symlink to `AGENTS.md`. Created if you selected Claude Code during init.       |
| `.cursorrules`                    | One-line directive for Cursor. Created if you selected Cursor during init.     |
| `.windsurfrules`                  | One-line directive for Windsurf. Created if you selected Windsurf during init. |
| `.github/copilot-instructions.md` | Directive for GitHub Copilot. Created if you selected Copilot during init.     |
| `agent_docs/`                     | Deeper reference docs for your agent to load on demand.                        |
| `scripts/`                        | Maintenance scripts for init, validation, promotion, and compression.          |

`.agents.local.md` is added to `.gitignore` automatically. It is personal and should not be committed.

## Validate your setup

After init, run the following to confirm everything is wired up correctly:

```bash theme={null}
agent-context validate
```

The validate command checks that `AGENTS.md` exists and is under 120 lines, that `.agents.local.md` is gitignored, and that at least one agent tool config is present.

## Other CLI commands

```bash theme={null}
agent-context init                  # Set up context system in current project
agent-context validate              # Check setup is correct
agent-context promote               # Find patterns ready to move to AGENTS.md
agent-context promote --autopromote # Auto-append patterns recurring 3+ times
```

## After setup

Once init completes:

1. **Fill in `AGENTS.md`** with your actual project name, stack, commands, and the patterns and gotchas specific to your codebase.
2. **Fill in `agent_docs/`** with deeper references your agent should load on demand — architecture decisions, full conventions, extended gotchas. Delete any sections that do not apply.
3. **Customize `.agents.local.md`** with your personal preferences (planning style, code preferences, tone).
4. **Work normally.** Your agent reads `AGENTS.md` and `.agents.local.md` at session start, does the task, and updates the scratchpad at session end.
5. **Promote what sticks.** When a pattern recurs across three or more sessions, the agent flags it in the scratchpad's "Ready to Promote" section. You decide when to move it into `AGENTS.md`.