Troubleshooting

When a skill fails, it prints what went wrong. Find the message below.

Common errors

Agent cannot see the key

The skills read the key only from the ROUTEMUX_API_KEY environment variable.

1. Check that your terminal has it (this does not print the key):

   [ -n "$ROUTEMUX_API_KEY" ] && echo set || echo missing

2. If it says missing, add this line to ~/.zshrc (zsh) or ~/.bashrc (bash), then open a new terminal:

   export ROUTEMUX_API_KEY='sk-...'

3. Start the agent from that terminal. An agent started there inherits the key.

Agents started from the Dock or a desktop launcher do not read your shell profile, so they may not see the key. Start them from a terminal instead — or, if your agent cannot see the key, set it in the agent's own config and restart the agent:

Claude Code — add it to the env object in ~/.claude/settings.json:

{
  "env": {
    "ROUTEMUX_API_KEY": "sk-..."
  }
}

Codex — add it under [shell_environment_policy] in ~/.codex/config.toml:

[shell_environment_policy]
set = { ROUTEMUX_API_KEY = "sk-..." }

Either file then holds your key in plain text, the same as a shell profile does.

Codex

• Skills location. Codex reads user skills from ~/.agents/skills, not ~/.codex/skills. The npx command and the install script both install there. If you copied the skills by hand, move them to ~/.agents/skills.

• Restart after installing. Codex picks up new skills when it starts.

• Calling a skill. Type $routemux-images or $routemux-video, or just ask in plain words.

• Network approval. The first time a skill runs curl, Codex may ask you to approve network access. Approve it, or allow network access for good in ~/.codex/config.toml:

  [sandbox_workspace_write]
  network_access = true

Duplicate skills

If each skill shows up twice in Claude Code, you installed it both as a plugin and with npx (or the script). Keep one:

• Remove the plugin: /plugin uninstall routemux@routemux
• Or remove the npx/script copy: delete the routemux-* folders in ~/.claude/skills

Update

• npx: run the install command again — npx skills add https://routemux.com -g
• Install script: run it again — curl -fsSL https://routemux.com/.well-known/agent-skills/install.sh | sh
• Claude Code plugin: run /plugin marketplace update routemux, or turn on auto-update for the marketplace in /plugin.
• Manual download: download the zips again from the index.

Uninstall

• Claude Code plugin: /plugin uninstall routemux@routemux
• Everything else: delete the routemux-* folders from your agent's skills directory. If you installed with npx, also delete them from ~/.agents/skills — npx keeps its copy there and links it into the other agents' directories.

If you no longer need the key on this machine, also delete the export ROUTEMUX_API_KEY=... line from your shell profile.