Skip to content
Agents Pack

File layout

File layout

Section titled “File layout”

Agents Pack keeps lifecycle state in one scope root, edits user-owned content only under a canonical user/ tree, and renders provider-native files where Claude Code, Codex, and Cursor expect them.

See Ownership, Safety and drift, and Repository vs global.

Scope roots

Section titled “Scope roots”
Scope State root
Repository .agents-pack/ at the Git repository root (or the current directory if there is no Git root)
Global ~/.agents-pack/

Only one active Agents Pack scope is supported at a time. If both global and the current repository are initialized, Agents Pack reports a scope conflict.

Lifecycle state

Section titled “Lifecycle state”

Under the active scope root, Agents Pack stores installation configuration, locks, transaction recovery data, and related lifecycle files. Repository-generated state is normally reviewed and committed with the project so teammates share the same setup.

Do not commit the user-level pack cache (below).

User-owned canonical source

Section titled “User-owned canonical source”

Edit custom skills and subagents only here. Generated provider copies are derived from these trees by agents-pack sync.

Scope Canonical user root
Repository .agents-pack/user/
Global ~/.agents-pack/user/

Typical layout:

.agents-pack/user/                 # or ~/.agents-pack/user/
├── skills/
│   └── <name>/
│       └── SKILL.md
└── subagents/
    └── <name>/
        ├── agent.toml
        └── instructions.md

Example skill path after agents-pack create skill deploy-app:

.agents-pack/user/skills/deploy-app/SKILL.md

eject, official update, and rollback preserve this canonical user directory. Eject removes generated provider copies and lifecycle state, not your user/ sources.

Provider output paths

Section titled “Provider output paths”

Agents Pack renders into native locations for the selected agents. Exact paths depend on scope and agent combination. Only paths required by the selected agents and components are created.

Repository scope

Section titled “Repository scope”
.claude/rules/agents-pack/
.claude/skills/
.claude/agents/
AGENTS.md
.agents/skills/
.codex/agents/
.cursor/rules/agents-pack/
.cursor/skills/
.cursor/agents/

Notes:

  • Codex instructions use a marked managed block inside AGENTS.md. Text outside that block remains yours.
  • Agents Pack may reuse Claude or Codex skill roots for Cursor instead of writing a third identical copy, and reports discovery warnings when relevant.
  • Direct edits to generated copies are drift and block sync or other mutations until resolved. See Safety and drift.

Global scope

Section titled “Global scope”

Global installations use the corresponding locations under your home directory for Claude Code and Codex. Global Cursor is not supported. See Platforms and agents.

Shared pack cache

Section titled “Shared pack cache”

Cached pack artifacts live under:

~/.agents-pack/cache/packs/

install, remove, and rollback rely on exact cached packs. Do not manually delete this cache while an installation depends on it. Rollback never downloads missing historical versions; it only restores packs already cached on this machine.

What to commit

Section titled “What to commit”

Usually commit in a repository installation:

  • .agents-pack/ lifecycle state and configuration
  • .agents-pack/user/ canonical sources
  • generated provider files such as .claude/, AGENTS.md, .agents/, .codex/, and .cursor/ paths that Agents Pack manages

Do not commit ~/.agents-pack/cache/.

Section titled “Related”