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:

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.

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.

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

4. Sync after pulling teammates' changes

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.