agrx — Run Skills Without Installing¶

Tldr

agrx downloads a skill, runs it with your AI tool's CLI, and cleans up afterwards. Nothing is added to agr.toml. Use it to try skills before committing to an install.

Prerequisites: agr installed and the tool CLI for your chosen AI tool (e.g., claude, codex, agent)

agrx is like npx for AI agent skills. It downloads a skill from GitHub, runs it with your AI coding tool's CLI, and cleans up afterwards. Nothing is added to agr.toml — no permanent install, no project changes.

Key terms: A skill is a directory containing a SKILL.md file with instructions for an AI coding agent. A handle like anthropics/skills/pdf identifies a skill on GitHub (user/repo/skill). The short form user/skill assumes a repo named skills. A tool is one of the supported AI coding agents: Claude Code, Cursor, Codex, OpenCode, GitHub Copilot, or Antigravity.

Quick Start¶

agrx anthropics/skills/pdf                          # Run once, then clean up

Downloading anthropics/skills/pdf...
Running skill 'pdf' with claude...

agrx anthropics/skills/pdf -p "Extract tables"      # Pass a prompt
agrx kasperjunge/commit -i                          # Interactive: skill + chat

How It Works¶

Determine tool — Uses --tool flag, or default_tool from agr.toml, or the first tool in tools, or claude (see Supported Tools)
Download skill — Clones the repo and extracts the skill (same as agr add, using handles)
Install temporarily — Places the skill in your tool's skills directory with a unique _agrx_ prefix so it doesn't conflict with permanent installs
Run the tool's CLI — Invokes the tool (e.g., claude -p "/skill-name")
Clean up — Removes the temporary skill directory, even on Ctrl+C

Permission-bypass flags in interactive mode

When you use -i (interactive mode), agrx passes a tool-specific flag to reduce permission prompts during the session:

Tool	Flag (with `-i` only)
Claude Code	`--dangerously-skip-permissions`
OpenAI Codex	`--full-auto`
GitHub Copilot	`--allow-all-tools`

Cursor, OpenCode, and Antigravity don't have a permission-bypass flag.

Without -i, the tool runs in non-interactive mode (prompt-and-exit) and no permission-bypass flag is passed — you'll see normal permission prompts if the skill takes actions that require approval.

Options¶

Flag	Short	Description
`--tool`	`-t`	Tool CLI to use (claude, cursor, codex, opencode, copilot, antigravity)
`--interactive`	`-i`	Run skill, then continue in interactive mode
`--prompt`	`-p`	Prompt to pass to the skill
`--global`	`-g`	Install to global skills directory instead of project-local
`--source`	`-s`	Use a specific source from `agr.toml`

Examples¶

Run with a specific tool¶

agrx anthropics/skills/pdf --tool codex

Downloading anthropics/skills/pdf...
Running skill 'pdf' with codex...

agrx anthropics/skills/pdf --tool cursor
agrx anthropics/skills/pdf --tool opencode

Interactive mode¶

The -i flag runs the skill first, then starts an interactive session so you can continue the conversation:

agrx kasperjunge/commit -i

Downloading kasperjunge/commit...
Running skill 'commit' with claude...

Pass a prompt¶

agrx anthropics/skills/pdf -p "Extract all tables from report.pdf as CSV"

Downloading anthropics/skills/pdf...
Running skill 'pdf' with claude...

Use a custom source¶

See Configuration — Sources for how to set up custom sources.

agrx team/internal-skill --source my-server

Downloading team/internal-skill...
Running skill 'internal-skill' with claude...

Run outside a git repo¶

agrx requires a git repository by default. Use --global to run anywhere:

agrx anthropics/skills/pdf --global

Downloading anthropics/skills/pdf...
Running skill 'pdf' with claude...

Differences from `agr add`¶

	`agr add`	`agrx`
Persists skill	Yes (permanent install)	No (cleaned up after run)
Updates `agr.toml`	Yes (adds dependency)	No
Runs the skill	No	Yes (invokes tool CLI)
Local paths	Supported	Not supported (remote only)
Multi-tool	Installs to all configured tools	Uses one tool

Common Errors¶

Running agrx on a local path fails — only remote handles are supported:

agrx ./my-skill

Error: agrx only works with remote handles
Use 'agr add' for local skills

Running outside a git repo without --global:

agrx anthropics/skills/pdf

Error: Not in a git repository
Use --global to install to ~/.claude/skills/

Tool CLI Requirements¶

agrx needs the tool's CLI to be installed. If it's missing, you'll see an error with installation instructions:

Tool	CLI	Install
Claude Code	`claude`	claude.ai/download
Cursor	`agent`	Install Cursor IDE
OpenAI Codex	`codex`	`npm i -g @openai/codex`
OpenCode	`opencode`	opencode.ai/docs/cli
GitHub Copilot	`copilot`	Install GitHub Copilot CLI
Antigravity	—	No CLI available; use `agr add` to install skills instead

Next Steps¶

Tutorial — Full walkthrough including using agrx to try skills
Skill Directory — Browse available skills to run with agrx
CLI Reference — Complete agrx command reference with all flags
Troubleshooting — Fix common errors with skill downloads and tool CLIs