# Agent Resources (agr)

> **agr** stands for *agent resources* — the package manager your team uses to manage its coding-agent resources. agr manages two resource types: **skills** (`SKILL.md` folders consumed by AI coding tools) and **ralphs** (`RALPH.md` folders defining autonomous agent loops, executed by a ralph runtime such as [ralphify](https://github.com/kasperjunge/ralphify)). Install, share, and sync resources across Claude Code, Cursor, Codex, OpenCode, Copilot, and Antigravity — built for teams practicing Agentic Engineering.

For the complete documentation in a single file, see [llms-full.txt](https://computerlovetech.github.io/agr/llms-full.txt).

## Quick Start

```bash
uv tool install agr
agr add anthropics/skills/frontend-design
```

Run once without installing:

```bash
agrx anthropics/skills/pdf -p "Extract tables from report.pdf"
```

## Documentation Map

### Getting Started
- [Home](https://computerlovetech.github.io/agr/) — Install agr, add your first skill, and see what's available
- [Tutorial](https://computerlovetech.github.io/agr/tutorial/) — Step-by-step guide from install to sharing your own skill
- [Core Concepts](https://computerlovetech.github.io/agr/concepts/) — How skills, handles, sources, and scopes work

### Guides
- [Supported Tools](https://computerlovetech.github.io/agr/tools/) — Claude Code, Cursor, Codex, OpenCode, Copilot, Antigravity
- [Skill Directory](https://computerlovetech.github.io/agr/skills/) — Browse official and community skills
- [Ralph Directory](https://computerlovetech.github.io/agr/ralphs/) — RALPH.md format and how to install ralphs (autonomous agent loops)
- [Teams](https://computerlovetech.github.io/agr/teams/) — Set up agr for a team with shared skills and CI/CD
- [Configuration](https://computerlovetech.github.io/agr/configuration/) — Multi-tool setup, custom sources, instruction syncing
- [agrx](https://computerlovetech.github.io/agr/agrx/) — Run skills ephemerally without installing

### Building Skills
- [Creating Skills](https://computerlovetech.github.io/agr/creating/) — Write, test, and publish AI agent skills
- [Python SDK](https://computerlovetech.github.io/agr/sdk/) — Use agr as a library to load and inspect skills

### Reference
- [CLI Reference](https://computerlovetech.github.io/agr/reference/) — Every command, flag, and config option
- [Troubleshooting](https://computerlovetech.github.io/agr/troubleshooting/) — Common errors and how to fix them
- [What's New](https://computerlovetech.github.io/agr/changelog/) — Release notes and breaking changes

## All Commands

```bash
agr add user/skill         # Install a resource (skill or ralph) from GitHub
agr add user/repo/skill    # From a specific repo
agr add ./path/to/skill    # Local path
agr add user/skill -o      # Update to latest version, re-resolving the lock
agr remove user/skill      # Uninstall
agr sync                   # Install all dependencies from agr.toml, refresh agr.lock
agr sync --frozen          # CI deploy: install exactly what agr.lock specifies
agr sync --locked          # CI PR check: fail if agr.lock is stale vs agr.toml
agr list                   # Show installed resources
agr init                   # Create agr.toml (auto-detects tools)
agr init my-skill          # Scaffold a new skill
agr config show            # View current config
agr config set tools claude cursor  # Configure tools
agr config get <key>       # Read a config value
agrx user/skill            # Run a skill temporarily (skills only)
agrx user/skill -i         # Run, then continue chatting
```

Add `-g` to `add`, `remove`, `sync`, or `list` for global resources (available in all projects; ralphs are skipped in global scope).

## Handle Format

```
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
```

## agr.toml and agr.lock

agr tracks your project's resources in two committed files, like npm's `package.json` + `package-lock.json`:

- **`agr.toml`** — the hand-edited manifest. Dependencies, tools, sources, default owner, instruction syncing. Each dependency has `type = "skill"` or `type = "ralph"` (set automatically by `agr add`).
- **`agr.lock`** — auto-generated by `agr add`, `agr remove`, and `agr sync`. Pins the exact git commit SHA and content hash for every resolved dependency so installs are byte-identical across machines.

**Commit both.** `agr.toml` declares intent; `agr.lock` makes `agr sync` reproducible.

```toml
# agr.toml — hand-edited
tools = ["claude", "cursor", "codex"]
default_tool = "claude"

dependencies = [
    {handle = "anthropics/skills/frontend-design", type = "skill"},
    {handle = "vercel-labs/agent-browser/agent-browser", type = "skill"},
    {path = "./skills/local-skill", type = "skill"},
    {handle = "your-username/agent-resources/bug-hunter", type = "ralph"},
]

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

```toml
# agr.lock — auto-generated, do not edit
version = 1

[[skill]]
handle = "anthropics/skills/frontend-design"
source = "github"
commit = "a0d5bfd4d9658073029d33f979ac5a027568caec"
content-hash = "sha256:75e47183c30bc8651e76286680eddac88a3024a7ee5a7f1bc486d4d3fdee34ce"
installed-name = "frontend-design"

[[ralph]]
handle = "your-username/agent-resources/bug-hunter"
source = "github"
commit = "9859f7bceb7a46af8482cabb9aa24e0d38a49413"
content-hash = "sha256:fa1ce825fa7e11cd5aac55ee7eac5e9c918e3af113b7988fdbd281a319acc110"
installed-name = "bug-hunter"
```

Teammates install everything with `agr sync`. CI uses `agr sync --frozen` (install exactly what `agr.lock` specifies) or `agr sync --locked` (fail if `agr.lock` is stale).

## Supported Tools

agr installs skills into 6 AI coding tools. Configure with `agr config set tools claude cursor codex`.

| Tool | Config name | Invoke skill | Project skills dir | Instruction file |
|------|-------------|-------------|-------------------|-----------------|
| Claude Code | claude | /skill-name | .claude/skills/ | CLAUDE.md |
| Cursor | cursor | /skill-name | .cursor/skills/ | AGENTS.md |
| OpenAI Codex | codex | $skill-name | .agents/skills/ | AGENTS.md |
| OpenCode | opencode | skill-name | .opencode/skills/ | AGENTS.md |
| GitHub Copilot | copilot | /skill-name | .github/skills/ | AGENTS.md |
| Antigravity | antigravity | (via IDE) | .gemini/skills/ | GEMINI.md |

## Ralphs

A **ralph** is the second resource type agr manages. It is a directory containing a `RALPH.md` file that defines an autonomous agent loop — an `agent` command, shell `commands` whose stdout is captured into placeholders like `{{ commands.tests }}`, and `args` injected via `{{ args.<name> }}`. agr packages and distributes ralphs; a ralph runtime such as [ralphify](https://github.com/kasperjunge/ralphify) runs them.

Install with the same commands as skills — `agr add`, `agr sync`, `agr remove`, `agr list` all work transparently. agr auto-detects the type: local paths by marker file (`RALPH.md` vs `SKILL.md`), and remote handles by searching for a skill first and falling back to a ralph. Ralphs install once per project into `.agents/ralphs/<name>/` — there is no per-tool fan-out, and `-g` (global) is not supported for ralphs. `agrx` is skill-only.

Minimal `RALPH.md`:

```markdown
---
agent: claude -p --dangerously-skip-permissions
commands:
  - name: tests
    run: uv run pytest -x
args:
  - focus
---

# Bug Hunter

Autonomous bug-hunting agent. Each iteration starts fresh; progress lives in the code.

## Tests

{{ commands.tests }}

## Task

Find and fix a real bug. {{ args.focus }}
```

Run with a ralph runtime:

```bash
uvx ralphify run .agents/ralphs/bug-hunter --max-iterations 5 --focus "fix parser"
```

Full guide: [Ralph Directory](https://computerlovetech.github.io/agr/ralphs/).

## SKILL.md Format

Every skill is a directory with a `SKILL.md` file containing YAML frontmatter:

```markdown
---
name: my-skill
description: What this skill does and when to use it.
---

Instructions for the AI agent go here.
```

Required fields: `name` (1–64 chars, lowercase alphanumeric and hyphens) and `description` (max 1024 chars).

## Python SDK

Use agr as a Python library to load skills programmatically:

```python
from agr import Skill, list_skills, skill_info, cache

# Load a skill from GitHub (cached locally)
skill = Skill.from_git("anthropics/skills/code-review")
print(skill.prompt)   # SKILL.md contents
print(skill.files)    # Files in the skill directory

# Load from local path
skill = Skill.from_local("./my-skill")

# Discover skills in a repo
for info in list_skills("anthropics/skills"):
    print(f"{info.handle}: {info.name}")

# Get description for a specific skill
info = skill_info("anthropics/skills/code-review")
print(info.description)

# Manage the download cache
cache.info()                        # {"skills_count": N, "size_bytes": N}
cache.clear()                       # Clear all cached skills
cache.clear("anthropics/skills/*")  # Clear by pattern
```

All errors inherit from `agr.exceptions.AgrError`. Key subclasses: `SkillNotFoundError`, `RepoNotFoundError`, `AuthenticationError`, `RateLimitError`, `InvalidHandleError`, `InvalidLocalPathError`, `CacheError`.

Full SDK docs: [Python SDK](https://computerlovetech.github.io/agr/sdk/)

## Source Code

- GitHub: https://github.com/computerlovetech/agr
- PyPI: https://pypi.org/project/agr/
- Skills Specification: https://agentskills.io/specification
- Example Skills: https://github.com/anthropics/skills

## License

MIT License
