Core Concepts¶

Tldr

agr has five building blocks: skills (folders with a SKILL.md), handles (like user/skill) to reference them, tools (Claude Code, Cursor, etc.) that consume them, sources (where to fetch from), and scopes (local per-project vs global). agr.toml ties it all together.

This page explains the building blocks of agr. Read it after the Tutorial to understand why things work the way they do, or skim it before diving into Configuration.

Skills¶

A skill is a folder containing a SKILL.md file. The file has YAML frontmatter (name, description) and a markdown body with instructions for an AI coding agent.

my-skill/
├── SKILL.md          # Required — agent instructions
├── scripts/          # Optional — helper scripts
│   └── validate.sh
└── references/       # Optional — reference docs
    └── api-schema.json

When you install a skill, agr copies this entire directory into your tool's skills folder. The AI tool reads SKILL.md and follows the instructions when the skill is invoked.

Skills are tool-agnostic. The same SKILL.md works in Claude Code, Cursor, Codex, OpenCode, Copilot, and Antigravity — agr installs it into the right place for each tool.

See Creating Skills for how to write one, or browse the Skill Directory for published skills you can install.

Handles¶

A handle is how you refer to a skill. It tells agr where to find it.

Remote handles¶

user/skill            →  github.com/user/skills  repo, "skill" directory
user/repo/skill       →  github.com/user/repo    repo, "skill" directory

The two-part form (user/skill) assumes the skill lives in a repo named skills. If it doesn't, use the three-part form (user/repo/skill).

Local handles¶

./path/to/skill       →  Local directory on disk

Local handles point to a skill directory on your filesystem. They're useful for testing skills before publishing or for project-specific skills that don't need a remote repo.

How agr resolves a handle to files on disk¶

Every remote handle follows the same three-step flow — clone, search, copy:

Clone — agr sparse-checkouts the repo from GitHub (fast, even for large repos)
Search — it finds a directory named after the skill that contains SKILL.md
Copy — it installs that directory into each configured tool's skills folder

The handle format determines which repo gets cloned:

Handle	Repo cloned	When to use
`user/skill`	`github.com/user/skills`	Default — repo is always named `skills`
`user/repo/skill`	`github.com/user/repo`	Skills live in a differently named repo

The two-part form is the most common. It's why the recommended way to share skills is a repo named skills under your GitHub username.

agr searches recursively regardless of nesting depth (skills/skill/, resources/skills/skill/, skill/). When multiple matches exist, the shallowest path wins.

Wrong handle format?

If agr add user/repo fails because it's actually a repo (not a skill in the skills repo), agr probes the repo and suggests the correct three-part handles — so you don't have to guess.

Tools¶

A tool is an AI coding agent that reads skills. agr supports six:

Tool	Config name	How skills are invoked
Claude Code	`claude`	`/skill-name`
Cursor	`cursor`	`/skill-name`
OpenAI Codex	`codex`	`$skill-name`
OpenCode	`opencode`	`skill-name`
GitHub Copilot	`copilot`	`/skill-name`
Antigravity	`antigravity`	(via IDE)

Each tool has its own skills directory where agr installs skills:

Tool	Project directory	Global directory
Claude Code	`.claude/skills/`	`~/.claude/skills/`
Cursor	`.cursor/skills/`	`~/.cursor/skills/`
OpenAI Codex	`.agents/skills/`	`~/.agents/skills/`
OpenCode	`.opencode/skills/`	`~/.config/opencode/skills/`
GitHub Copilot	`.github/skills/`	`~/.copilot/skills/`
Antigravity	`.gemini/skills/`	`~/.gemini/skills/`

When you configure multiple tools, agr add and agr sync install skills into all of them simultaneously. Configure your tools with:

agr config set tools claude cursor codex

How skills are named on disk¶

Skills are installed using their plain name — agr add anthropics/skills/pdf creates a pdf/ directory inside each tool's skills folder.

If two different handles share the same skill name (e.g., alice/skills/lint and bob/tools/lint), agr falls back to a fully-qualified directory name (alice--skills--lint/, bob--tools--lint/) to avoid collisions. You'll still invoke the skill by its plain name in your tool — agr handles the mapping.

See Supported Tools for details on each tool.

Sources¶

A source defines where agr fetches remote skills from. The default source is GitHub:

[[source]]
name = "github"
type = "git"
url = "https://github.com/{owner}/{repo}.git"

The {owner} and {repo} placeholders are filled from the handle. For example, agr add anthropics/skills/pdf clones https://github.com/anthropics/skills.git.

You can add custom sources for GitLab, self-hosted Git servers, or any host that supports Git over HTTPS:

agr config add sources gitlab --url "https://gitlab.com/{owner}/{repo}.git"
agr add team/skill --source gitlab

Set a default source so you don't have to pass --source every time:

agr config set default_source gitlab

See Configuration — Sources for more.

Scopes: Local vs Global¶

agr has two scopes:

Local (default) — Skills installed in the current project. Tracked in ./agr.toml. Installed into project-level directories (e.g., .claude/skills/). These skills are only available when working in this project.

Global (-g flag) — Skills available everywhere. Tracked in ~/.agr/agr.toml. Installed into per-tool global directories (e.g., ~/.claude/skills/). These skills are available in every project.

agr add anthropics/skills/pdf              # Local: this project only
agr add -g anthropics/skills/skill-creator  # Global: every project

Use local for project-specific skills that teammates should share (see Teams for the full team setup). Use global for personal utilities you want everywhere.

The two scopes are independent — a skill can be installed both locally and globally without conflict.

agr.toml¶

agr.toml is the manifest file that tracks your skill dependencies and configuration. It's similar to package.json or pyproject.toml — commit it to version control so your team shares the same skills.

tools = ["claude", "cursor"]
default_tool = "claude"

dependencies = [
    {handle = "anthropics/skills/frontend-design", type = "skill"},
    {handle = "anthropics/skills/pdf", type = "skill"},
    {path = "./skills/internal-review", type = "skill"},
]

How agr finds it¶

agr looks for agr.toml starting from the current directory and searching upward through parent directories until it finds one or reaches the filesystem root. This means you can run agr commands from any subdirectory in your project.

For global scope (-g), agr uses ~/.agr/agr.toml.

Creating it¶

You don't need to create agr.toml manually. It's created automatically by:

agr init — Creates the file and auto-detects your tools
agr add — Creates the file if it doesn't exist

See Configuration for all options and Reference — agr.toml Format for the full schema.

Keep Instruction Files Aligned Across Tools¶

Different tools use different instruction files:

File	Tools
`CLAUDE.md`	Claude Code
`AGENTS.md`	Cursor, Codex, OpenCode, Copilot
`GEMINI.md`	Antigravity

If you use multiple tools, you can designate one file as canonical and have agr copy its content to the others automatically:

agr config set sync_instructions true
agr config set canonical_instructions CLAUDE.md
agr sync   # Copies CLAUDE.md content to AGENTS.md, GEMINI.md as needed

This keeps all your tools aligned without maintaining multiple files manually.

`agr` vs `agrx` — Permanent Install vs One-Off Run¶

agr ships two commands:

agr — The main CLI for managing skills. Install, remove, sync, list, configure. Changes persist in agr.toml and your tool's skills directories.

agrx — The ephemeral runner. Downloads a skill, runs it with your tool's CLI, and cleans up. Nothing is saved. Think of it as npx for skills.

agr add anthropics/skills/pdf         # Permanent: install and track
agrx anthropics/skills/pdf            # Temporary: run once and clean up

Use agr when you want a skill to stick around. Use agrx when you want to try something quickly or run a one-off task.

See agrx for full details. You can also load skills programmatically with the Python SDK.

The Full `agr add` Install Flow¶

When you run agr add anthropics/skills/pdf, agr parses the handle, clones the repo (sparse checkout), finds the pdf/SKILL.md directory, copies it into each configured tool's skills folder, and updates agr.toml.

Full install flow (7 steps)

Parse the handle — anthropics is the owner, skills is the repo, pdf is the skill name
Load config — Read agr.toml (or create it) to find configured tools and sources
Clone the repo — Sparse-checkout github.com/anthropics/skills
Find the skill — Recursively search for a directory named pdf containing SKILL.md
Install to each tool — Copy the skill directory to each configured tool's skills folder (e.g., .claude/skills/pdf/, .cursor/skills/pdf/)
Write metadata — Save .agr.json in each installed copy with the source handle, install details, and content hash
Update agr.toml — Add the dependency to the manifest

If any tool's install fails, already-installed copies are rolled back automatically.

Next Steps¶

Configuration — Multi-tool setup, custom sources, instruction syncing
Supported Tools — Detailed info on each tool's behavior
Creating Skills — Write and share your own skills
Reference — Every command, flag, and config option
Troubleshooting — Fix common errors and edge cases