Get Started with agr¶
Tldr
uv tool install agr → cd your-project → agr add anthropics/skills/frontend-design
→ use /frontend-design in your AI tool. Share via agr.toml in git;
teammates run agr sync. Create your own: agr init my-skill.
This tutorial walks you through a complete workflow — installing agr, adding skills to a project, syncing with a team, and creating your own skill. By the end you'll understand how all the pieces fit together.
Time: ~10 minutes Prerequisites: Python 3.10+, git, a Python package installer (uv, pipx, or pip), and at least one supported AI coding tool (Claude Code, Cursor, Codex, OpenCode, Copilot, or Antigravity)
Step 1: Install agr¶
Verify it works:
This installs two commands:
agr— the main CLI for installing, managing, and syncing skillsagrx— an ephemeral runner that downloads a skill, runs it once, and cleans up
Step 2: Set up a project¶
Navigate to a project where you use an AI coding tool:
You can optionally run agr init to create agr.toml up front:
This creates an agr.toml file and auto-detects which
tools you use based on repo signals (.claude/, CLAUDE.md,
.cursor/, .cursorrules, etc.):
Skip this step
agr init is optional. If you jump straight to agr add in the next step,
agr auto-creates agr.toml and detects your tools automatically.
Your agr.toml starts with the defaults and an empty dependency list:
default_source = "github"
dependencies = []
[[source]]
name = "github"
type = "git"
url = "https://github.com/{owner}/{repo}.git"
Step 3: Add your first skill¶
Install a skill from GitHub:
What just happened:
- agr cloned the
anthropics/skillsrepo (via sparse checkout — fast, even for large repos) - It found the
frontend-designdirectory containing aSKILL.mdfile - It copied that skill into your tool's skills folder (e.g.,
.claude/skills/frontend-design/) - It added the dependency to
agr.toml
Check your agr.toml — it now tracks the skill:
List what's installed:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━┓
┃ Skill ┃ Type ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━┩
│ anthropics/skills/frontend-design │ remote │ installed │
└───────────────────────────────────┴────────┴───────────┘
Use the skill¶
Open your AI coding tool and invoke the skill. How you invoke it depends on which tool you use:
| Tool | Invoke with |
|---|---|
| Claude Code | Type /frontend-design in the chat |
| Cursor | Type /frontend-design in the chat |
| OpenAI Codex | Type $frontend-design in the chat |
| OpenCode | Type frontend-design in the chat |
| GitHub Copilot | Type /frontend-design in the chat |
| Antigravity | Use through the IDE interface |
In most tools, skills also load as context automatically — the agent may apply them without you explicitly invoking them. See Supported Tools for details on each tool's behavior.
Step 4: Add more skills¶
Browse the Skill Directory for more options, or install multiple skills at once:
Or install from a specific user's repo using the three-part handle format:
Handle format cheat sheet¶
| Handle | What it resolves to |
|---|---|
user/skill |
github.com/user/skills repo, skill directory |
user/repo/skill |
github.com/user/repo repo, skill directory |
./path/to/skill |
Local directory on disk |
Step 5: Team sync¶
Your agr.toml is meant to be committed to version control. When a teammate
clones the repo, they run:
This installs every skill listed in agr.toml that isn't already present. It's
like npm install for agent skills:
Up to date: anthropics/skills/frontend-design
Up to date: anthropics/skills/pdf
Up to date: anthropics/skills/skill-creator
Summary: 3 up to date
For a full walkthrough on multi-tool teams, CI/CD, and private repos, see Teams.
Step 6: Try a skill without installing¶
Sometimes you want to test a skill before committing to it. That's what
agrx is for:
This downloads the skill to a temporary location, runs it with your tool's CLI,
and cleans up afterwards. Nothing is added to agr.toml.
Use -i to start an interactive session after the skill runs:
Step 7: Create your own skill¶
Scaffold a new skill:
This creates my-skill/SKILL.md with a starter template:
---
name: my-skill
description: TODO — describe what this skill does and when to use it
---
# my-skill
## When to use
Describe when this skill should be used.
## Instructions
Provide detailed instructions here.
Edit the file to describe what you want the agent to do. The
frontmatter (name, description) is required.
The body after the frontmatter is the actual instruction content that gets
loaded by your AI tool.
Skill structure¶
A minimal skill is just a SKILL.md file in a directory. But skills can include
supporting files too:
my-skill/
├── SKILL.md # Required — skill instructions
├── scripts/ # Optional — helper scripts the skill references
│ └── lint.sh
└── templates/ # Optional — templates or examples
└── component.tsx
Test it locally¶
Install your skill from the local path:
Now open your AI tool and verify the skill works as expected. Iterate on the
SKILL.md content until you're happy, then reinstall with --overwrite:
Step 8: Share your skill¶
Push your skill to GitHub. The recommended structure is a repo named skills
under your GitHub username:
Once pushed, anyone can install it:
If your skills live in a differently named repo, users reference it with the three-part format:
Going further¶
Remove a skill
This deletes the skill from your tool's skills folder and removes the entry
from agr.toml.
Install skills globally (available in every project)
Some skills are useful across every project — not just one. Add -g to
install globally:
Global skills are tracked in ~/.agr/agr.toml. Sync and list them with:
What's next¶
- Core Concepts — understand handles, tools, sources, and how agr works under the hood
- Creating Skills — detailed guide on writing effective skills, including frontmatter options and supporting files
- Configuration — multi-tool setup, custom sources, private repos, and instruction syncing
- agrx — full reference for the ephemeral skill runner
- Python SDK — use agr as a library in your own tools
- CLI Reference — every command, flag, and option