Skip to content

Reference

Tldr

agr add installs skills, agr sync installs everything from agr.toml, agr config manages settings. agrx runs skills ephemerally. Handles: user/skill, user/repo/skill, or ./local. Add -g for global scope.

Complete reference for all agr and agrx commands. For guided setup, start with the Tutorial.

What is agr? A package manager for AI agent skills. A skill is a folder with a SKILL.md file containing instructions for an AI coding agent — see Creating Skills to build your own. A handle like user/skill or user/repo/skill points to a skill on GitHub. Browse available skills in the Skill Directory. agr installs skills into supported tools including Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, and Antigravity. agr.toml tracks dependencies — commit it so your team shares the same skills.

Quick Reference

Install & Remove

agr add user/skill                     # Install from GitHub
agr add user/repo/skill                # Install from a specific repo
agr add ./path/to/skill                # Install from local directory
agr add user/skill user/other-skill    # Install multiple at once
agr add user/skill --overwrite         # Update to latest version
agr remove user/skill                  # Uninstall a skill

Global Skills

agr add -g user/skill                  # Install globally (all projects)
agr list -g                            # List global skills
agr sync -g                            # Sync global dependencies
agr remove -g user/skill               # Remove a global skill

Team Sync

agr sync                               # Install all skills from agr.toml
agr list                               # Show skills and install status

Try Without Installing

agrx user/skill                        # Run once, then clean up
agrx user/skill -p "Extract tables"    # Pass a prompt
agrx user/skill -i                     # Interactive: skill + chat
agrx user/skill --tool cursor          # Use a specific tool

Create & Share

See the full Creating Skills guide for details.

agr init my-skill                      # Scaffold a new skill
agr add ./my-skill                     # Test locally
agr add ./my-skill -o                  # Reinstall after editing

Configuration

agr init                               # Create agr.toml (auto-detects tools)
agr config show                        # View current config
agr config set tools claude cursor     # Target multiple tools
agr config set default_tool claude     # Set default for agrx
agr config add tools codex             # Add a tool without replacing
agr config remove tools codex          # Stop syncing to a tool (⚠ deletes its skills)

Removing a tool deletes its skills

agr config remove tools <name> also deletes all skills from that tool's skills directory. Skills remain in your other configured tools and can be reinstalled with agr config add tools <name>.

Handle Format

agr add user/skill                 # github.com/user/skills repo, "skill" directory
agr add user/repo/skill            # github.com/user/repo repo, "skill" directory
agr add ./path/to/skill            # Local directory on disk

Two-part handles (user/skill) assume a repo named skills. Use three parts when the repo has a different name. See Handle Resolution for the full lookup rules.

Sources & Private Repos

export GITHUB_TOKEN="ghp_aBcDeFgHiJkL01234567890mNoPqRsTuVwXy"  # Authenticate for private repos
agr config add sources gitlab \
  --url "https://gitlab.com/{owner}/{repo}.git"              # Custom source
agr add user/skill --source gitlab               # Use a specific source
agr config set default_source gitlab             # Change default source

Instruction Syncing

agr config set sync_instructions true             # Enable syncing
agr config set canonical_instructions CLAUDE.md   # Set source of truth
agr sync                                          # Copies to AGENTS.md, GEMINI.md

Global Options

These apply to all agr commands (not agrx):

  • --quiet, -q — Suppress non-error output
  • --version, -v — Show version and exit

CLI Commands

agr add

Install skills from GitHub or local paths. Skills are installed into your tool's skills folder (e.g. .claude/skills/, .agents/skills/, .cursor/skills/, .opencode/skills/, .github/skills/, .gemini/skills/).

If no agr.toml exists, agr add creates one automatically and detects which tools you use from repo signals. You don't need to run agr init first.

agr add <handle>...

Arguments:

  • handle — Skill handle (user/skill or user/repo/skill) or local path (./path)

Options:

  • --overwrite, -o — Replace existing skills
  • --source, -s <name> — Use a specific source from agr.toml
  • --global, -g — Install globally using ~/.agr/agr.toml and tool global directories

Examples:

agr add anthropics/skills/frontend-design
agr add -g anthropics/skills/frontend-design
agr add kasperjunge/commit kasperjunge/pr
agr add ./my-skill
agr add anthropics/skills/pdf --overwrite
agr add anthropics/skills/pdf --source github

agr remove

Uninstall skills from all configured tools and remove them from agr.toml. Each skill is deleted from every tool's skills directory (e.g., .claude/skills/, .cursor/skills/) and its dependency entry is removed from the manifest.

agr remove <handle>...

Arguments:

  • handle — Skill handle or local path (same formats as agr add)

Options:

  • --global, -g — Remove from global skills directory and ~/.agr/agr.toml

Examples:

agr remove anthropics/skills/frontend-design
agr remove -g anthropics/skills/frontend-design
agr remove kasperjunge/commit
agr remove ./my-skill

agr sync

Install all dependencies from agr.toml, sync instruction files, and run any pending directory migrations.

agr sync

Synced instructions: CLAUDE.md -> AGENTS.md
Up to date: anthropics/skills/frontend-design
Up to date: anthropics/skills/pdf
Installed: kasperjunge/commit

Summary: 2 up to date, 1 installed

Each agr sync run performs up to three stages before reporting results:

  1. Instruction sync — copies the canonical instruction file to other tools' instruction files (only when sync_instructions = true and 2+ tools are configured)
  2. Migrations — renames skill directories to match current naming conventions (e.g., Cursor nested → flat, Codex .codex/ → .agents/, OpenCode .opencode/skill/ → .opencode/skills/, Antigravity .agent/ → .gemini/). This happens automatically — no manual steps needed.
  3. Dependency install — installs any skills from agr.toml that are not yet present. Skills from the same repository are batched into a single download.

Options:

  • --global, -g — Sync global dependencies from ~/.agr/agr.toml

agr list

Show all skills and their installation status.

agr list

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Skill                             ┃ Type   ┃ Status               ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ anthropics/skills/frontend-design │ remote │ installed            │
│ anthropics/skills/pdf             │ remote │ partial (claude)     │
│ kasperjunge/commit                │ remote │ not synced           │
│ ./skills/local-skill              │ local  │ installed            │
└───────────────────────────────────┴────────┴──────────────────────┘

Status values:

Status Meaning
installed Installed in all configured tools
partial (tool1, tool2) Installed in some tools but not all — lists which tools have it
not synced Listed in agr.toml but not installed in any tool. Run agr sync to install.
invalid Handle in agr.toml cannot be parsed. Check the handle format.

Partial installs

You'll see partial status when using multiple tools and a skill is only installed in some of them. Run agr sync to install the missing copies, or agr add <handle> --overwrite to reinstall everywhere.

Options:

  • --global, -g — List global skills from ~/.agr/agr.toml

agr init

Create agr.toml or a skill scaffold.

agr init              # Create agr.toml
agr init <name>       # Create skill scaffold

agr init creates agr.toml and auto-detects which tools you use from repo signals (.claude/, CLAUDE.md, .cursor/, .cursorrules, etc.).

Options:

  • --tools — Comma-separated tool list (e.g., claude,codex,opencode)
  • --default-tool — Default tool for agrx and instruction sync
  • --sync-instructions/--no-sync-instructions — Sync instruction files on agr sync
  • --canonical-instructions — Canonical instruction file (AGENTS.md, CLAUDE.md, or GEMINI.md)

Examples:

agr init                    # Creates agr.toml in current directory
agr init my-skill           # Creates my-skill/SKILL.md
agr init --tools claude,codex,opencode --default-tool claude
agr init --sync-instructions --canonical-instructions CLAUDE.md

agr config

Manage agr.toml configuration.

agr config show

Config: /Users/you/project/agr.toml

  tools                    = claude, codex, opencode
  default_tool             = claude
  default_source           = github
  sync_instructions        = true
  canonical_instructions   = CLAUDE.md

Sources:
  - github [git] https://github.com/{owner}/{repo}.git (default)

agr config path

/Users/you/project/agr.toml

agr config get tools

claude codex opencode

All subcommands:

agr config show                              # View formatted config
agr config path                              # Print agr.toml path
agr config edit                              # Open in $VISUAL or $EDITOR
agr config get <key>                         # Read a config value
agr config set <key> <values>                # Write scalar or replace list
agr config add <key> <values>                # Append to list
agr config remove <key> <values>             # Remove from list
agr config unset <key>                       # Clear to default

Valid keys: tools, default_tool, default_source, sync_instructions, canonical_instructions, sources

Options (on all subcommands):

  • --global, -g — Operate on ~/.agr/agr.toml instead of local

Options (on add only):

  • --type — Source type (when key is sources). Defaults to git.
  • --url — Source URL (when key is sources)

Examples:

agr config set tools claude codex opencode
agr config set default_tool claude
agr config add tools cursor
agr config remove tools cursor            # ⚠ deletes skills from that tool
agr config set sync_instructions true
agr config set canonical_instructions CLAUDE.md
agr config add sources my-source --url "https://git.example.com/{owner}/{repo}.git"
agr config unset default_tool

agrx

Run a skill temporarily without adding to agr.toml.

agrx <handle> [options]

Downloads the skill, runs it with the selected tool, and cleans up afterwards. See the agrx guide for usage patterns and examples.

Options:

  • --tool, -t — Tool CLI to use (claude, cursor, codex, opencode, copilot, antigravity). Overrides default_tool from config.
  • --interactive, -i — Run skill, then continue in interactive mode
  • --prompt, -p — Prompt to pass to the skill
  • --global, -g — Install to the global tool skills directory instead of the repo-local one
  • --source, -s <name> — Use a specific source from agr.toml

Examples:

agrx anthropics/skills/pdf
agrx anthropics/skills/pdf -p "Extract tables from report.pdf"
agrx kasperjunge/commit -i
agrx kasperjunge/commit --source github

agr.toml Format

default_source = "github" # (1)!
tools = ["claude", "codex", "opencode"] # (2)!
default_tool = "claude" # (3)!
sync_instructions = true # (4)!
canonical_instructions = "CLAUDE.md" # (5)!

dependencies = [ # (6)!
    {handle = "anthropics/skills/frontend-design", type = "skill"},
    {handle = "kasperjunge/commit", type = "skill"},
    {handle = "team/internal-tool", type = "skill", source = "my-server"}, # (7)!
    {path = "./local-skill", type = "skill"}, # (8)!
]

[[source]] # (9)!
name = "github"
type = "git"
url = "https://github.com/{owner}/{repo}.git"
  1. Source used when --source is not passed to agr add or agrx
  2. Skills are installed into all listed tools on every agr add and agr sync
  3. Tool used by agrx and for instruction sync — defaults to the first in tools
  4. Copies the canonical instruction file to other tools on agr sync
  5. The instruction file treated as the source of truth (CLAUDE.md, AGENTS.md, or GEMINI.md)
  6. Must appear before any [[source]] blocks — each entry needs type = "skill" plus either handle or path
  7. Pin a dependency to a specific source instead of using default_source
  8. Local path dependencies point to a directory on disk — no Git fetch needed
  9. Each [[source]] defines a Git server URL template with {owner} and {repo} placeholders

Python SDK

For programmatic access to skills, use the Python SDK — it provides Skill, list_skills, skill_info, and caching APIs.

Troubleshooting

See the Troubleshooting page for solutions to common errors — installation failures, handle format issues, authentication problems, and more.

What's New

See the Changelog for release notes, new features, and breaking changes.

Next Steps

  • Creating Skills — Build and publish your own skills
  • Core Concepts — Understand handles, sources, and scopes
  • Teams — Share skills across your team with agr.toml