Skip to main content
AEP is entirely repo-local and file-based. There is no server to run and no package to install. Setting up a repo takes three steps: create the directory structure, copy the template files, and configure your agent to load packs automatically.
1

Create the directory structure

Create the agent directory for your active agent and the aep/ subfolder inside it. Use AGENTS.md as the shared instruction file that all agents can read.For a new install, choose the directory that matches your active agent (see Agent compatibility for the full list). The example below uses .agent/ as a generic placeholder — replace it with .claude/, .opencode/, .cursor/, .codex/, or .gemini/ as appropriate.
mkdir -p .agent/aep/tasks
touch .agent/AGENTS.md
The resulting structure:
.agent/
  AGENTS.md
  aep/
    index.json
    project.aep.json
    user.aep.json
    tasks/
Do not create .agent/ for new installs if you are using a specific agent. Prefer the agent-aware directory (.claude/aep/, .opencode/aep/, etc.) so packs are co-located with the agent’s own config.
2

Copy the template files

Copy the AEP template files into your agent directory. The templates give you a valid starting point for each pack type.
Template sourceDestination
assets/templates/project.aep.json<agent-dir>/aep/project.aep.json
assets/templates/user.aep.json<agent-dir>/aep/user.aep.json
assets/templates/index.json<agent-dir>/aep/index.json
assets/templates/task.generic.aep.json (optional)<agent-dir>/aep/tasks/<task>.aep.json
# Example using .agent/ — replace with your actual agent directory
cp path/to/aep/assets/templates/project.aep.json .agent/aep/project.aep.json
cp path/to/aep/assets/templates/user.aep.json    .agent/aep/user.aep.json
cp path/to/aep/assets/templates/index.json       .agent/aep/index.json

# Optional: seed a starter task pack
cp path/to/aep/assets/templates/task.generic.aep.json \
   .agent/aep/tasks/my-first-task.aep.json
The starter index.json references the project, user, and optional task pack entries so the agent can discover all packs from a single file:
{
  "version": "1.0-exp",
  "packs": [
    {
      "id": "project-defaults",
      "scope": "project",
      "version": "1.0-exp",
      "path": "project.aep.json",
      "tags": [],
      "strength": 0.6,
      "updated_at": "2026-03-31T00:00:00Z"
    },
    {
      "id": "user-collaboration-style",
      "scope": "user",
      "version": "1.0-exp",
      "path": "user.aep.json",
      "tags": [],
      "strength": 0.6,
      "updated_at": "2026-03-31T00:00:00Z"
    },
    {
      "id": "generic-task-pattern-exp",
      "scope": "task",
      "version": "1.0-exp",
      "path": "tasks/generic-task-pattern-exp.aep.json",
      "tags": [],
      "strength": 0.5,
      "updated_at": "2026-03-31T00:00:00Z"
    }
  ]
}
3

Configure agent behavior

Add AEP loading instructions to your agent’s instruction file so every future session starts with packs loaded. Edit AGENTS.md (and any agent-specific file such as CLAUDE.md or a Cursor rules file) to include the following minimum content:
# AEP - Agent Experience Protocol

Before starting tasks, load relevant AEP packs from <agent-dir>/aep/.
Apply task packs first, then project, then user packs.
After successful tasks, save new or updated AEP packs.
Replace <agent-dir> with the actual directory path (e.g. .claude, .opencode, .cursor).The agent will now:
  1. Read AGENTS.md at the start of each session.
  2. Load <agent-dir>/aep/index.json to discover all available packs.
  3. Score and rank packs against the current task using keywords, applies_to, and strength.
  4. Apply the top 1–3 packs as alignment rules before executing the task.
  5. Save new or updated packs after successful tasks.

​
Complete directory structure

After setup, your repo will contain the following AEP files (example using .agent/): 
.agent/
  AGENTS.md                         ← shared agent instructions
  aep/
    index.json                      ← pack registry (all packs listed here)
    project.aep.json                ← project-scope constraints and preferences
    user.aep.json                   ← user-scope collaboration style
    tasks/
      my-first-task.aep.json        ← task-specific pack (optional at setup)
      html-to-nextjs.aep.json       ← added later by `aep save`
    runs/                           ← optional evidence from past runs
      2026-03-31T10-00-00Z-abc123/
        transcript.summary.md
        signals.json
        outcome.json
        generated-pack.json

​
How the agent knows to use AEP

Once AGENTS.md is in place and contains AEP loading instructions, the agent reads it automatically at session start. From that point on:
  • aep apply — the agent loads and scores packs before any substantial task.
  • aep save — after a successful task, the agent saves a new pack and updates index.json.
  • aep promote — the agent promotes task-level patterns up to project or user scope.
  • aep inspect — the agent reports which packs are active, their scores, and usage metrics.
You do not need to repeat your preferences in every session. The packs carry them forward.

Agent compatibility

Agent-specific directories and instruction file updates

Matching and scoring

How agents rank AEP packs for every task

Pack overview

Task, project, and user pack types explained

Template reference

Starter templates for all pack types

Build docs developers (and LLMs) love

Get started for freeTalk to us