Skip to main content
A user pack captures how you prefer to work with agents — your explanation style, decision-making approach, and communication preferences. Unlike task and project packs, a user pack is not tied to any specific repo. It travels with you, providing a consistent baseline collaboration style wherever you work.

​
What user packs capture

User packs encode the personal layer of your working style:
  • Collaboration style — how you like to interact during a task (e.g. prefer step-by-step confirmation before large changes, or prefer autonomous execution with a summary at the end)
  • Explanation preferences — how much context you want the agent to provide (e.g. explain reasoning for non-obvious choices, skip boilerplate commentary)
  • Decision-making patterns — how you like decisions framed when there are trade-offs (e.g. present options with pros and cons, or just proceed with the best choice)
  • Output format preferences — how you want results structured and presented
  • Communication preferences — tone, verbosity, and format of agent responses
Because the user pack applies across all projects, keep it focused on preferences that are genuinely about you — not about any particular codebase.

​
File location

There is one user pack per agent installation, stored at: 
<agent-dir>/aep/user.aep.json
For example: 
.claude/aep/user.aep.json
.opencode/aep/user.aep.json
To carry your user pack between repos, copy user.aep.json to the same relative path in the new repo’s agent directory. Because it lives in the repo, you control how it travels.

​
How user packs travel between repos

User packs are repo-local files, which means you manage portability yourself. The recommended pattern:
1

Maintain a personal copy

Keep a canonical version of your user.aep.json in a personal dotfiles repo or a notes directory that you sync between machines.
2

Copy when setting up a new repo

When you initialize AEP in a new project, copy your user pack alongside the project and index templates:
cp ~/dotfiles/aep/user.aep.json .claude/aep/user.aep.json
3

Sync updates back

When you refine your user pack in one repo, copy the updated version back to your canonical location so future repos start with the improved version.
Track your personal user.aep.json in a git-managed dotfiles repo. This gives you version history for your collaboration preferences and makes it easy to deploy the same baseline across every project you work on.

​
Fields: what to populate

The same fields exist in all pack types, but for user packs the meaning shifts toward personal style rather than task mechanics:
FieldWhat to put here for a user pack
intentDescribe your general collaboration philosophy (e.g. “Prefer iterative refinement over large upfront designs”)
constraintsRules that always apply regardless of task (e.g. “Always ask before deleting files”)
preferencesStyle preferences like verbosity, tone, and explanation depth
workflowYour preferred task rhythm (e.g. confirm plan before executing, summarize at end)
failure_trapsPatterns you’ve found disruptive across many sessions
success_checksWhat a good collaboration looks like to you

​
Template

This is the complete user pack template from the AEP source: 
{
  "version": "1.0-exp",
  "id": "user-collaboration-style",
  "scope": "user",
  "title": "User collaboration style and preferences (experimental)",
  "status": "draft",
  "source": {
    "type": "successful_collaboration",
    "created_at": "2026-03-31T00:00:00Z",
    "confidence": 0.6
  },
  "match": {
    "keywords": [],
    "patterns": [],
    "tags": []
  },
  "applies_to": {
    "languages": [],
    "frameworks": [],
    "paths": [],
    "domains": []
  },
  "strength": 0.6,
  "intent": [
    "Describe how this user prefers to work with agents across projects using experimental metadata"
  ],
  "constraints": [],
  "preferences": [],
  "workflow": [],
  "failure_traps": [],
  "success_checks": [],
  "metrics": {
    "times_applied": 0,
    "first_used_at": "2026-03-31T00:00:00Z",
    "last_used_at": "2026-03-31T00:00:00Z",
    "avg_turns_saved": 0
  },
  "history": [
    {
      "at": "2026-03-31T00:00:00Z",
      "event": "created",
      "reason": "Initial experimental user-level AEP template"
    }
  ],
  "merge_suggestions": [],
  "artifacts": {
    "examples": [],
    "notes": "Use this to encode explanation style, decision-making preferences, and collaboration workflow that should travel with the user between repos."
  }
}
The applies_to fields are less critical for user packs than for task packs. A user pack applies universally, so leaving applies_to empty or setting broad values is appropriate. The agent will load it regardless of language or framework context.

​
When to update the user pack

Update the user pack when you notice a preference or workflow pattern holding up consistently across multiple projects and task types.
1

Notice a cross-project pattern

After several successful sessions, look for preferences that you keep finding yourself wishing were loaded by default — things you’ve added to multiple project packs that are really about you, not the project.
2

Promote from a project pack

Tell the agent: "Use the AEP skill and promote the preferences from the project pack to my user pack." The agent extracts user-level signals and adds them to user.aep.json, recording the event in both packs’ history.
3

Edit directly

You can also update the user pack directly by editing user.aep.json. Add a history entry:
{
  "at": "2026-04-15T10:00:00Z",
  "event": "updated",
  "reason": "Added preference: always confirm plan before making changes to more than 3 files"
}
4

Sync to your canonical copy

After refining the user pack, copy the updated file back to your personal dotfiles or notes so the improvement carries forward to future repos.

​
Override behavior

The user pack has the lowest override priority. Both task packs and project packs override user pack signals. 
user pack      ← lowest priority, applies everywhere
  ↑ overridden by
project pack   ← applies across the whole repo
  ↑ overridden by
task pack      ← highest priority, applies per task type
This means your personal preferences form the broadest baseline, and more specific packs can refine or override them for particular repos or task types. A task pack can suppress a user-level preference for a single task type without changing your global defaults.
Because the user pack is overridden by both project and task packs, be careful about treating it as a source of truth for constraints that genuinely must be enforced everywhere. Hard requirements that should never be overridden are better enforced through agent instruction files (AGENTS.md, CLAUDE.md, etc.) rather than the user pack.

Pack types overview

Understand all three scopes and how they work together.

Project packs

Repo-wide constraints that override the user pack.

Promote guide

Step-by-step guide to promoting preferences across scopes.

Schema reference

Full field reference for user pack fields.

Build docs developers (and LLMs) love

Get started for freeTalk to us