agr-cli

# agr CLI

agr is the package manager for AI agent skills. It installs, shares, and syncs
SKILL.md folders across Claude Code, Cursor, Codex, OpenCode, GitHub Copilot,
and Pi. This skill helps you operate the `agr` CLI on the user's
behalf — set up new repos, install and sync skills, manage `agr.toml` /
`agr.lock`, and scaffold in-repo skills under `skills/`.

## When to use

Use this skill when the user wants to:

- Install or remove a remote skill (`agr add anthropics/skills/pdf`).
- Sync `agr.toml` after pulling teammates' changes (`agr sync`).
- Upgrade an installed skill past its pinned commit (`agr upgrade`).
- Run a skill once without persisting it (`agrx ...`) or invoke an installed one (`agr run`).
- Scaffold a new skill (`agr init my-skill`) — especially as in-repo skills under `skills/`.
- Set up a repo from scratch to use agr (multi-tool config, instruction syncing, sources).
- Add a local in-repo skill to the project's dependency list.
- Inspect, edit, or troubleshoot `agr.toml` / `agr.lock` / `agr config`.
- Or whenever `agr.toml` is present and the user is doing resource-management work.

Do NOT use this skill for:

- Authoring the *body* of a SKILL.md. This skill scaffolds and registers; for
  writing effective skill instructions, defer to the user or to a dedicated
  authoring skill such as `anthropics/skills/skill-creator`.
- Iterating on an existing skill based on session feedback or a retrospective.
  That's a separate workflow — listen, propose, edit, commit, re-install. If
  the user has a dedicated debrief / improvement skill installed (e.g.
  `skill-debrief`), use it; otherwise just do the workflow directly.

## Prerequisites

Before running anything, verify agr is installed:

```bash
agr --version
```

If missing, the standard install is `uv tool install agr`. **Do not install agr
without checking with the user first** — they may prefer pipx, brew, or a
pinned version in CI.

## Mental model — read first

- A **skill** is a folder containing a `SKILL.md`. agr copies the whole folder
  into each configured AI tool's skills directory (`.claude/skills/`,
  `.cursor/skills/`, `.opencode/skills/`, `.agents/skills/`, etc.).
- A **handle** identifies a remote skill: `user/skill` (assumes a repo named
  `skills`), `user/repo/skill` (any repo), or `./local/path` (on disk).
- `agr.toml` is the **manifest** (hand-edited or written by `agr add`).
  `agr.lock` is the **lockfile** (auto-generated, pins commit SHAs and content
  hashes — never edit by hand).
- **Project-local** vs **global** scope: every command takes `-g` to operate on
  `~/.agr/agr.toml` and global tool dirs.
- `agr sync` only installs *missing* deps. To move past a pinned commit, use
  `agr upgrade`.
- Resource types: **skill** (consumed by AI tools), **ralph** (autonomous
  agent loop), **package** (a folder with its own `agr.toml`, expanded
  transitively). `agr add` auto-detects the type.

For the full conceptual model: [references/handles.md](references/handles.md).

## Workflows

### 1. Set up a new repo for agr

When the user wants to start using agr in a project that has none configured:

1. Run `agr init`. agr auto-detects which AI tools the repo uses
   (`.claude/`, `CLAUDE.md`, `.cursor/`, `.cursorrules`, `.codex/`, `.opencode/`,
   `.github/copilot-instructions.md`, `.pi/`, `.agents/`) and writes `agr.toml`.
2. Confirm or adjust the detected tools. For multi-tool:
   `agr config set tools claude codex opencode`.
3. If the user maintains a canonical instruction file (e.g. `CLAUDE.md`) and
   wants it mirrored to others (`AGENTS.md`), enable instruction
   syncing: `agr config set sync_instructions true` then
   `agr config set canonical_instructions CLAUDE.md`.
4. Commit `agr.toml`. (`agr.lock` will appear after the first `agr add` or
   `agr sync` — commit it too.)

Full details: [references/setup.md](references/setup.md).

### 2. Install a skill

```bash
agr add anthropics/skills/pdf
```

Notes:

- Multi: `agr add user/skill1 user/skill2` (skills from the same repo are
  batched into one download).
- `--overwrite` / `-o` to replace.
- `-g` for global (available in every project).
- `agr add` auto-creates `agr.toml` if missing — no need to `agr init` first.

For handle formats and private repos: [references/handles.md](references/handles.md)
and [references/installing-skills.md](references/installing-skills.md).

### 3. In-repo skills (the recommended workflow for skills shipping with the codebase)

Place project-specific skills under `skills/` at the repo root (or at the root
of a relevant submodule). This keeps the skill in version control, reviewable
in PRs, and sharable across the team via `agr.toml`.

```bash
agr init my-skill                  # scaffolds my-skill/SKILL.md in CWD
mkdir -p skills && mv my-skill skills/
agr add ./skills/my-skill          # records {path = "./skills/my-skill", type = "skill"} in agr.toml
```

Iterate: edit `skills/my-skill/SKILL.md`, then
`agr add ./skills/my-skill --overwrite` to reinstall into each configured tool.

Teammates pick it up with `agr sync` after pulling. The local `path` dependency
travels with the repo, so contributors don't need network access to use it.

For structuring (scripts/, references/, assets/), iteration patterns, and
testing with `agrx`: [references/in-repo-skills.md](references/in-repo-skills.md).

### 4. Sync after pulling teammates' changes

```bash
agr sync
```

This (1) syncs instruction files, (2) runs directory migrations, (3) installs
any deps missing for any tool, (4) refreshes `agr.lock`.

CI flags:

- `agr sync --frozen` — install exactly what `agr.lock` says; fail if lock is
  missing or doesn't cover all deps. Use in deploy pipelines for byte-identical
  installs.
- `agr sync --locked` — fail if `agr.lock` is stale vs `agr.toml`. Use in PR
  checks to enforce lockfile hygiene.
- `--frozen` and `--locked` are mutually exclusive.

Full lifecycle: [references/syncing.md](references/syncing.md).

### 5. Upgrade past pinned c