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.