Fix Common agr Errors

Tldr

Most issues come from wrong handle formats (user/skill not skill), missing GITHUB_TOKEN for private repos, or stale installs (fix with agr add --overwrite). Error messages include hints — read them first.

Key terms: A skill is a directory containing a SKILL.md file with YAML frontmatter (name, description) and markdown instructions for an AI coding agent. A handle identifies a skill on GitHub: user/skill (from user's skills repo), user/repo/skill (from a specific repo), or ./path/to/skill (local). A tool is a supported AI coding agent (Claude Code, Cursor, Codex, OpenCode, Copilot, or Antigravity). A source is a Git server URL template where agr fetches remote skills from (default: GitHub).

Quick links: Installation · Handle Format · Configuration · Syncing · Sources · Creating Skills · Global Installs · agrx

Installation

How do I fix "git CLI not found"?

Error: git CLI not found. Install git to fetch remote skills.

agr uses git under the hood for all remote operations. Install it:

macOSUbuntu/DebianWindows

xcode-select --install

sudo apt install git

Download from git-scm.com.

How do I fix "Repository not found"?

Error: Repository 'user/skills' not found in source 'github'.

The repository doesn't exist or is private. Check:

1. Typo in the handle? Verify the username and repo name on GitHub.
2. Private repo? Set a GitHub token (see Private Repositories):

   export GITHUB_TOKEN="ghp_aBcDeFgHiJkL01234567890mNoPqRsTuVwXy"
   

3. Non-default repo name? Use the three-part handle format:

   agr add user/my-custom-repo/skill-name
   

How do I fix "Authentication failed"?

Error: Authentication failed for source 'github'.

Your GitHub token is missing, expired, or lacks permissions.

• No token set? Export one:

  export GITHUB_TOKEN="ghp_aBcDeFgHiJkL01234567890mNoPqRsTuVwXy"
  # or
  export GH_TOKEN="$(gh auth token)"
  

• Token expired? Generate a new one at github.com/settings/tokens.
• Wrong permissions? The token needs Contents: Read-only access on the target repository. Fine-grained tokens are recommended.

How do I fix "Skill not found in repository"?

Error: Skill 'myskill' not found in repository.
No directory named 'myskill' containing SKILL.md was found.
Hint: Create a skill at 'skills/myskill/SKILL.md' or 'myskill/SKILL.md'

The repo exists but doesn't contain a skill with that name. agr searches recursively for a directory matching the skill name that contains a SKILL.md file.

Fix: Follow the hint to create the skill, or check the repo on GitHub to see what skills are available. If you used a two-part handle, agr may suggest corrections:

Skill 'myskill' not found. However, 'user/myskill' exists as a repository with 3 skill(s):
  agr add user/myskill/skill1
  agr add user/myskill/skill2
  agr add user/myskill/skill3

How do I fix "Skill not found in sources"?

Error: Skill 'myskill' not found in sources: github

agr searched all configured sources and couldn't find a matching skill anywhere. This differs from "Skill not found in repository" — that one means the repo was found but the skill directory wasn't in it. This error means no source had a repo containing the skill.

Fix:

1. Check the handle. Verify the username and skill name are correct.
2. Try the three-part format if the skill lives in a non-default repo:

   agr add user/custom-repo/myskill
   

3. Check your sources. If using custom sources, verify they're configured:

   agr config get sources
   

How do I fix "Skill already exists"?

Error: Skill already exists at /path/to/skill. Use --overwrite to replace.

The skill is already installed. To update it:

agr add user/skill --overwrite

Or remove it first:

agr remove user/skill
agr add user/skill

How do I fix "Network error: could not resolve host"?

Error: Network error: could not resolve host for source 'github'.

DNS resolution failed. Check your internet connection, VPN, or proxy settings.

How do I fix "Failed to clone repository"?

Error: Failed to clone repository from source 'github'.

This is a catch-all error when git clone fails for a reason agr can't classify (not auth, not network, not "repo not found"). Common causes:

• Disk full — free up space and try again
• File permission issues — check write access to your temp directory ($TMPDIR or /tmp)
• Corrupt local git state — clear the agr cache: python -c "from agr import cache; cache.clear()"
• Corporate proxy or firewall — git may be blocked. Try cloning the repo manually: git clone https://github.com/user/repo.git

If the manual clone works but agr add doesn't, open an issue with the full error output.

---

Handle Format

How do I fix "Invalid handle: remote handles require username/name format"?

Error: Invalid handle 'commit': remote handles require username/name format

A single word is treated as a local path. For remote skills, use the handle format:

# Wrong
agr add commit

# Right
agr add kasperjunge/commit

How do I fix "Too many path segments"?

Error: Invalid handle 'a/b/c/d': too many path segments (expected user/name or user/repo/name)

Handles support at most three parts: user/repo/skill. Check for extra slashes.

How do I fix "Contains reserved sequence '--'"?

Error: Invalid handle 'user/my--skill': skill name 'my--skill' contains reserved sequence '--'

Skill names cannot contain consecutive hyphens. Rename the skill to use single hyphens (e.g., my-skill instead of my--skill).

---

Configuration

How do I fix "No agr.toml found"?

No agr.toml found.
Run 'agr init' to create one.

You're running a command that requires agr.toml but the file doesn't exist yet. Create one:

agr init

How do I fix "Not in a git repository"?

Error: Not in a git repository

Project-level commands need to run inside a git repo. Either cd into one or initialize git:

git init

For agrx, use --global to run outside a git repo:

agrx anthropics/skills/pdf --global

How do I fix "Unknown tool"?

Error: Unknown tool 'photoshop' in agr.toml. Available: claude, cursor, codex, opencode, copilot, antigravity

Check your agr.toml for typos in the tools list. See Supported Tools for details on each:

Config name	Tool
claude	Claude Code
cursor	Cursor
codex	OpenAI Codex
opencode	OpenCode
copilot	GitHub Copilot
antigravity	Antigravity

Why does agr init detect a tool I don't use?

agr init auto-detects tools by looking for specific files and directories in your repo. Some detection signals are shared between tools:

Signal	Detected tools
.agents/	OpenAI Codex and Antigravity

For example, if you use Codex and have an .agents/ directory, agr also detects Antigravity because both tools use that directory. This is intentional — the .agents/ path follows the Agent Skills spec and both tools read skills from it.

To override detection and pick only the tools you want:

agr init --tools claude,codex

Or remove unwanted tools after setup:

agr config remove tools antigravity

See Supported Tools — Detection Signals for the full list per tool.

How do I fix "Cannot remove all tools. At least one must remain."?

Error: Cannot remove all tools. At least one must remain.

agr requires at least one tool in the tools list. You can't remove every tool — there'd be nowhere to install skills.

If you want to switch tools entirely, add the new one before removing the old:

agr config add tools codex
agr config remove tools claude

How do I fix "Invalid TOML in agr.toml"?

Error: Invalid TOML in agr.toml: ...

Your agr.toml has a syntax error. Common causes:

• Missing quotes around string values
• Unclosed brackets in dependencies or [[source]]
• Trailing commas after the last item in a list (TOML doesn't allow them)

Validate with any TOML linter, or paste your file into toml-lint.com to find the exact line.

How do I fix "default_tool must be listed in tools"?

Error: default_tool must be listed in tools in agr.toml

Your default_tool value isn't in your tools list. Either add it to tools or change default_tool:

# Wrong — codex isn't in tools
tools = ["claude", "cursor"]
default_tool = "codex"

# Right
tools = ["claude", "cursor", "codex"]
default_tool = "codex"

How do I fix "default_source not found in [[source]] list"?

Error: default_source 'my-server' not found in [[source]] list

Your agr.toml file has a default_source that refers to a source name that isn't defined in any [[source]] block. Either add the source or fix the name:

agr config add sources my-server --url "https://git.example.com/{owner}/{repo}.git"
# or fix the default
agr config set default_source github

How do I fix \"Source not found in sources list\" from agr config set?

Error: Source 'my-server' not found in sources list.
Hint: Available sources: github

This is similar to the error above, but happens when you run agr config set default_source my-server and the source doesn't exist yet. The hint shows which sources are available. Either add the source first or pick an existing one:

# Add the source first, then set it as default
agr config add sources my-server --url "https://git.example.com/{owner}/{repo}.git"
agr config set default_source my-server

# Or use an existing source
agr config set default_source github

How do I fix \"dependencies must be declared before [[source]] blocks\"?

Error: dependencies must be declared before [[source]] blocks

In agr.toml, the dependencies array must come before any [[source]] entries:

# Correct order
dependencies = [
    {handle = "user/skill", type = "skill"},
]

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

How do I fix \"Unknown source in dependency\"?

Error: Unknown source 'gitlab' in dependency 'user/skill'

A dependency specifies a source that isn't defined in your [[source]] list. Either add the source or remove the source field from the dependency:

# Add the missing source
agr config add sources gitlab --url "https://gitlab.com/{owner}/{repo}.git"

# Or edit agr.toml and remove source = "gitlab" from the dependency

How do I fix \"Dependency cannot have both handle and path\"?

Error: Dependency cannot have both handle and path

Each dependency must use handle or path, not both:

# Wrong — both handle and path
dependencies = [
    {handle = "user/skill", path = "./skills/skill", type = "skill"},
]

# Right — remote
dependencies = [
    {handle = "user/skill", type = "skill"},
]

How do I fix \"Dependency must have either handle or path\"?

Error: Dependency must have either handle or path

A dependency is missing both handle and path. Every dependency needs one:

# Right
dependencies = [
    {handle = "user/skill", type = "skill"},
]

How do I fix \"canonical_instructions must be 'AGENTS.md', 'CLAUDE.md', or 'GEMINI.md'\"?

Only these three instruction file names are supported for syncing. Other filenames like README.md or INSTRUCTIONS.md won't work.

How do I fix \"Cannot unset sources\"?

Error: Cannot unset sources. Use 'agr config remove sources <name>'.

Sources can't be cleared with unset because agr needs at least one source. Remove individual sources instead:

agr config remove sources my-server

How do I fix \"expects exactly one value\"?

Error: 'default_tool' expects exactly one value.

Scalar keys (default_tool, default_source, sync_instructions, canonical_instructions) accept a single value, not a list:

# Wrong — multiple values for a scalar key
agr config set default_tool claude cursor

# Right
agr config set default_tool claude

List keys (tools) accept multiple values with set:

agr config set tools claude cursor codex

How do I fix \"At least one tool name is required\"?

Error: At least one tool name is required.

You ran agr config set tools or agr config add tools without specifying any tool names. Provide at least one:

agr config set tools claude
agr config add tools cursor

How do I fix "sync_instructions must be 'true' or 'false'"?

Error: sync_instructions must be 'true' or 'false'.

The sync_instructions setting only accepts boolean values:

# Wrong
agr config set sync_instructions yes

# Right
agr config set sync_instructions true

How do I fix "Neither $VISUAL nor $EDITOR is set"?

Error: Neither $VISUAL nor $EDITOR is set.

agr config edit opens agr.toml in your default editor, but no editor is configured. Set one:

export EDITOR="vim"       # or nano, code, etc.
agr config edit

Add the export to your shell profile (~/.zshrc, ~/.bashrc) to make it permanent.

How do I fix "No global config found"?

Error: No global config found at ~/.agr/agr.toml
Hint: Run 'agr init' or create it manually.

You ran a global config command (agr config -g ...) but no global config exists yet. Create one by installing a skill globally:

agr add -g user/skill

This creates ~/.agr/agr.toml automatically.

How do I fix "Unknown config key"?

Error: Unknown config key 'tool'. Valid keys: canonical_instructions, default_source, default_tool, sources, sync_instructions, tools

You used a key name that agr config doesn't recognize. Common mistakes:

• tool instead of tools
• source instead of sources
• instructions instead of sync_instructions

How do I fix \"'default_tool' is a scalar. Use 'agr config set'\"?

Error: 'default_tool' is a scalar. Use 'agr config set default_tool <value>'.

You used agr config add or agr config remove on a scalar key. Scalar keys (default_tool, default_source, sync_instructions, canonical_instructions) accept a single value — use set to change them and unset to clear them:

# Wrong — add/remove are for list keys (tools, sources)
agr config add default_tool claude
agr config remove default_tool

# Right — use set/unset for scalar keys
agr config set default_tool claude
agr config unset default_tool

List keys (tools, sources) support add and remove.

How do I fix \"Cannot set sources directly\"?

Error: Cannot set sources directly. Use 'agr config add sources' and 'agr config remove sources'.

Sources can't be replaced in one shot with set. Add and remove them individually:

agr config add sources my-server --url "https://git.example.com/{owner}/{repo}.git"
agr config remove sources old-server

How do I fix \"--url is required when adding a source\"?

Error: --url is required when adding a source.

When adding a source, you must provide a URL template with {owner} and {repo} placeholders:

agr config add sources my-server --url "https://git.example.com/{owner}/{repo}.git"

How do I fix \"Source already exists\"?

Error: Source 'github' already exists.

To update it, remove the old one first:

agr config remove sources github
agr config add sources github --url "https://github.com/{owner}/{repo}.git"

How do I fix \"Tool is not in configured tools\"?

Error: Tool 'codex' is not in configured tools. Add it first with 'agr config add tools codex'.

Add the tool first, then set it as default:

agr config add tools codex
agr config set default_tool codex

How do I fix \"Unknown tool(s)\" from agr config?

Error: Unknown tool(s): photoshop
Hint: Available tools: claude, cursor, codex, opencode, copilot, antigravity

You passed an unrecognized tool name to agr config set tools, agr config add tools, or agr config remove tools. Check for typos — valid names are listed in the hint. See Supported Tools for details on each.

How do I fix \"Unknown default_tool in agr.toml\"?

Error: Unknown default_tool 'vscode' in agr.toml. Available: claude, cursor, codex, opencode, copilot, antigravity

Your default_tool is set to a tool name that agr doesn't recognize. This is different from default_tool must be listed in tools — that error means the tool is valid but not in your tools list. This one means the name itself is wrong:

agr config set default_tool claude

How do I fix \"Source name is required\" or \"Only one source name allowed\"?

Error: Source name is required.

Error: Only one source name allowed at a time.

When adding or removing sources, provide exactly one source name:

# Wrong — missing name
agr config add sources --url "https://..."

# Wrong — multiple names
agr config remove sources gitlab my-server

# Right
agr config add sources gitlab --url "https://gitlab.com/{owner}/{repo}.git"
agr config remove sources gitlab

How do I fix \"--type and --url are only valid for 'sources'\"?

Error: --type and --url are only valid for 'sources'.

The --type and --url flags only work with agr config add sources. You passed them to a different key:

# Wrong — --url doesn't apply to tools
agr config add tools claude --url "https://..."

# Right
agr config add sources my-server --url "https://git.example.com/{owner}/{repo}.git"

---

Syncing

How do I fix "No dependencies in agr.toml. Nothing to sync."?

Your agr.toml exists but has no dependencies entry. Add skills first:

agr add user/skill

This both installs the skill and adds it to agr.toml.

How do I fix "Instruction sync skipped: CLAUDE.md not found."?

You have sync_instructions = true but the canonical instruction file doesn't exist yet. Create it:

touch CLAUDE.md

Then run agr sync again.

Why does instruction sync not do anything?

You have sync_instructions = true but agr sync doesn't copy any instruction files. Two common causes:

1. Only one tool configured. Instruction syncing requires two or more tools — with a single tool, there's nothing to sync to. Add another tool:

   agr config set tools claude cursor
   agr sync
   

2. All tools use the same instruction file. If all your configured tools share the same instruction file (e.g., Cursor, Codex, and OpenCode all use AGENTS.md), there's nothing to copy. Syncing only helps when tools need different instruction files (e.g., Claude uses CLAUDE.md, Codex uses AGENTS.md).

Why does sync show "Up to date" but my skill seems outdated?

agr sync skips skills that are already installed. To force a fresh install from the latest version:

agr add user/skill --overwrite

This re-downloads the skill from GitHub and replaces your local copy.

---

Sources

How do I fix "Cannot remove default source"?

Error: Cannot remove default source 'my-server'. Change default_source first.

You can't remove a source that is currently set as default_source. Change the default first:

agr config set default_source github
agr config remove sources my-server

How do I fix \"Source not found\" when removing?

Error: Source 'my-server' not found.

The source you're trying to remove doesn't exist. Check the current sources:

agr config get sources

How do I fix \"Source entry missing name\"?

Error: Source entry missing name

Every [[source]] block needs a name field:

[[source]]
name = "my-server"
type = "git"
url = "https://git.example.com/{owner}/{repo}.git"

How do I fix \"Source missing url\"?

Error: Source 'my-server' missing url

Add the URL template:

[[source]]
name = "my-server"
type = "git"
url = "https://git.example.com/{owner}/{repo}.git"

How do I fix \"Unsupported source type\"?

Error: Unsupported source type 'svn' for 'my-server'

Error: Unsupported source type 'svn'. Only 'git' is supported.

Only git sources are supported. The first error appears when loading agr.toml with an invalid type in a [[source]] block. The second appears when running agr config add sources --type svn. In both cases, change the type to git.

How do I fix "GitHub API rate limit exceeded"?

Error: GitHub API rate limit exceeded

You've hit GitHub's API rate limit. This mainly affects the Python SDK (list_skills(), skill_info()) which use the GitHub API — not agr add or agr sync, which use Git clones.

• Authenticate to raise your limit. Unauthenticated requests are limited to 60/hour. With a token, you get 5,000/hour:

  export GITHUB_TOKEN="ghp_aBcDeFgHiJkL01234567890mNoPqRsTuVwXy"
  

• Wait for the limit to reset. GitHub rate limits reset hourly. Check your remaining quota with:

  curl -s -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/rate_limit | python3 -m json.tool
  

• In CI, cache results. If your pipeline calls list_skills() or skill_info() repeatedly, cache the output instead of calling the API on every run.

How do I fix "GitHub API authentication failed"?

Error: GitHub API authentication failed (HTTP 403)

This SDK-specific error means your GITHUB_TOKEN was rejected by the GitHub API. Unlike the git-level "Authentication failed" error (which fires during agr add), this one fires from SDK functions like list_skills() and skill_info().

• Token revoked or expired? Generate a new one at github.com/settings/tokens.
• Wrong token type? Fine-grained tokens need Contents: Read-only permission on the target repo.
• HTTP 401 vs 403: Both surface as this error. 401 means the token is invalid; 403 means it lacks permissions.

How do I fix "Failed to connect to GitHub API"?

Error: Failed to connect to GitHub API: <urlopen error ...>

The SDK couldn't reach api.github.com. This affects list_skills(), skill_info(), and other SDK functions that call the GitHub REST API.

• No internet? Check your connection.
• Corporate proxy or firewall? The GitHub API may be blocked. Try: curl -s https://api.github.com
• DNS issues? Same as the git-level "Network error: could not resolve host" — check VPN and DNS settings.

How do I fix \"Local skills cannot specify a source\"?

Error: Local skills cannot specify a source

The --source flag only applies to remote handles. Local paths are installed directly from disk:

# Wrong
agr add ./my-skill --source github

# Right
agr add ./my-skill

---

Creating Skills

How do I fix "Invalid skill name"?

Error: Invalid skill name 'My_Skill': must be 1-64 lowercase alphanumeric characters and hyphens, cannot start/end with a hyphen

Skill names must be lowercase alphanumeric with hyphens. No uppercase, underscores, spaces, or special characters. Names cannot start or end with a hyphen, and consecutive hyphens (--) are not allowed.

# Wrong
agr init "my skill"
agr init My_Skill
agr init MySkill
agr init -my-skill

# Right
agr init my-skill
agr init myskill
agr init code-reviewer

How do I fix \"Directory already exists\"?

Error: Directory 'myskill' already exists

agr init won't overwrite an existing directory. Either remove it or choose a different name.

How do I fix \"Local skill name is already installed\"?

Error: Local skill name 'my-skill' is already installed at /path/to/my-skill.

agr enforces unique names. Rename one skill or remove the existing one:

agr remove my-skill
agr add ./new-location/my-skill

How do I fix "not a valid skill (missing SKILL.md)"?

Error: './my-skill' is not a valid skill (missing SKILL.md)

The path doesn't contain a SKILL.md file. Create one and add the required frontmatter — see Creating Skills.

Why is my skill not showing up in my tool?

After agr add ./skills/my-skill, verify:

1. Check the skill directory exists in the tool's skills folder (e.g., .claude/skills/my-skill/SKILL.md).
2. Validate SKILL.md frontmatter — both name and description are required:

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

3. Restart the tool — some tools require a restart to pick up new skills.
4. Check agr list to see if the skill is registered.

---

Global Installs

How do I fix "No global agr.toml found"?

No global agr.toml found.
Run 'agr add -g <handle>' to create one.

There's no global config yet. Install a skill globally to create one:

agr add -g user/skill

The global config lives at ~/.agr/agr.toml.

---

agrx

How do I fix "Tool CLI not found"?

Error: codex CLI not found.

agrx needs the selected tool's CLI installed on your system. See which CLI each tool requires:

Tool	CLI command	Install
Claude Code	claude	claude.ai/download
Cursor	agent	Install the Cursor IDE
OpenAI Codex	codex	npm i -g @openai/codex
OpenCode	opencode	opencode.ai
GitHub Copilot	copilot	Install GitHub Copilot CLI

If you have the tool installed but agrx can't find it, check that the CLI is on your PATH:

which claude   # or codex, agent, opencode, copilot

How do I fix "agrx only works with remote handles"?

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

agrx downloads skills from GitHub and cleans up after running — it doesn't work with local paths. For local skills, install them permanently instead:

# Wrong
agrx ./skills/my-skill

# Right — install locally
agr add ./skills/my-skill

# Right — run a remote skill
agrx user/my-skill

Why can't I use agrx with Antigravity?

Antigravity does not have a standalone CLI, so agrx cannot run skills with it. Use agr add to install skills permanently, then invoke them through the Antigravity IDE interface.

How do I use agrx outside a git repository?

By default, agrx requires a git repo (to find agr.toml for tool/source config). Use --global to skip this:

agrx anthropics/skills/pdf --global

This installs the skill into the tool's global skills directory, runs it, and cleans up.

---

Still stuck?

• Run the failing command with details and check the output carefully — agr prints hints below most errors.
• Check GitHub Issues for known problems.
• Open a new issue with the full error output and your agr.toml contents.

Related Pages

• Configuration — Fix agr.toml settings, sources, and instruction sync issues
• Supported Tools — Check detection signals, skill directories, and CLI requirements per tool
• agrx — Fix issues with ephemeral skill runs, tool selection, and interactive mode
• CLI Reference — Verify command syntax, flags, and handle formats
• Creating Skills — Fix SKILL.md format, name validation, and testing issues
• Python SDK — Fix SDK-specific errors (rate limits, API auth, network failures)
• Teams — Fix CI/CD sync failures, private repo auth, and multi-tool team setup