/agr-cli

name: agr-cli
description: >
  Install, share, sync, and create AI agent skills across coding tools (Claude
  Code, Cursor, Codex, OpenCode, Copilot, Pi) using the agr CLI. Use
  whenever the user mentions agr, agr.toml, agr.lock, agrx, or asks to: add a
  skill ("install the pdf skill", "agr add ..."), sync agent resources across
  tools, share skills with their team, scaffold a new SKILL.md, run a skill
  ephemerally (agrx), set up a repo to manage AI agent dependencies, or
  configure tools/sources/instruction-syncing. Also use whenever an agr.toml
  or agr.lock is present in the project and the user is doing
  resource-management work.

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:

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

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`.

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 upgrade my-skill` to reinstall the fresh on-disk copy into each configured tool and refresh `agr.lock`. (`agr add ./skills/my-skill --overwrite` also works, but reach for it when you've changed the dependency's path or are re-adding it — for plain edits to an already-registered skill, `agr upgrade` is shorter and lock-aware.)

Teammates pick it up with `agr sync` after pulling.