# OpenRouter Agent Setup

These are instructions for you to establish a good AI development environment for OpenRouter. OpenRouter is a unified API for 600+ AI models.

There are a few actions to complete. Complete all of them, and continue forward if any one of them has issues.

- Install OpenRouter skills
- Check whether OPENROUTER_API_KEY is available
- Connect the OpenRouter MCP server (if this agent supports MCP)
- Identify the next thing the user should build with OpenRouter

IMPORTANT: The agent must do all steps it can do itself. Do not ask the user to run install commands. Only involve the user if they need to create an OpenRouter API key.

---

## Install OpenRouter Skills

Install all OpenRouter skills. Prefer user scope so the skills are available across future OpenRouter projects. Choose the first method that matches the current agent and works. Prefer native installers over npx. Only use npx methods when Node/npm are available.

Claude Code Plugin, if supported:

Use this if Claude Code has the OpenRouter skills repo available as a plugin. If these commands are unsupported or unavailable, use Claude Code npx fallback.

```
/plugin marketplace add OpenRouterTeam/skills
/plugin install openrouter@openrouter
```

Claude Code npx fallback:

```
npx -y skills add OpenRouterTeam/skills --skill '*' --yes --agent claude-code
```

Codex:

If the Codex skill-installer skill is available, use its GitHub repo install flow to install every skill directory from OpenRouterTeam/skills into CODEX_HOME/skills. If it needs explicit paths, list the repo first, then install each skill path. Tell the user to restart Codex.

Codex npx fallback:

```
npx -y skills add OpenRouterTeam/skills --skill '*' --yes --agent codex
```

Hermes:

```
hermes skills tap add https://github.com/OpenRouterTeam/skills
```

OpenClaw manual install:

```
git clone https://github.com/OpenRouterTeam/skills.git /tmp/openrouter-skills
mkdir -p ~/.agents/skills
cp -r /tmp/openrouter-skills/skills/* ~/.agents/skills/
rm -rf /tmp/openrouter-skills
openclaw skills list --eligible
```

npx fallback, Node required:

Use these only when npx is available. If npx is unavailable or fails, skip to GitHub Skill CLI fallback.

All:

```
npx -y skills add OpenRouterTeam/skills --skill '*' --yes
```

Cursor:

```
npx -y skills add OpenRouterTeam/skills --skill '*' --yes --agent cursor
```

Gemini CLI:

```
npx -y skills add OpenRouterTeam/skills --skill '*' --yes --agent gemini-cli
```

OpenCode:

```
npx -y skills add OpenRouterTeam/skills --skill '*' --yes --agent opencode
```

Windsurf:

```
npx -y skills add OpenRouterTeam/skills --skill '*' --yes --agent windsurf
```

GitHub Skill CLI fallback:

Use this if gh skill is available. If it is unavailable or fails, skip to Manual fallback.

```
gh skill install OpenRouterTeam/skills --skill '*' --scope user
```

Manual fallback, no Node required:

```
git clone https://github.com/OpenRouterTeam/skills.git /tmp/openrouter-skills
mkdir -p ~/.agents/skills
cp -r /tmp/openrouter-skills/skills/* ~/.agents/skills/
rm -rf /tmp/openrouter-skills
```

After installing, verify the files or installer output. If the current agent needs a restart, reload, or new session before skills activate, tell the user exactly that.

---

## Check OpenRouter API Key

Check whether OPENROUTER_API_KEY is available. Check only for presence. Do not print the value.

First check the current process environment.

If OPENROUTER_API_KEY is available there, validate it without revealing it by calling the OpenRouter key endpoint:

```bash
curl -sS https://openrouter.ai/api/v1/key -H "Authorization: Bearer $OPENROUTER_API_KEY" | head -c 300
```

If OPENROUTER_API_KEY is missing from the current process environment and the current agent is Hermes, also check Hermes' env file. Get the path with:

```bash
hermes config env-path
```

Then check that file for the presence of OPENROUTER_API_KEY without printing the value.

If the key is found in the Hermes env file, treat setup as complete and validate the key by loading it safely and calling the OpenRouter key endpoint. Do not blindly source the whole env file if it may contain values with spaces or shell-special characters.

If the key is missing from both the process environment and the agent-specific env file, tell the user to get a key at https://openrouter.ai/keys and add it to the appropriate place:

- For Hermes: add OPENROUTER_API_KEY to the Hermes env file returned by hermes config env-path, then reload or restart Hermes.
- For other agents or shells: add OPENROUTER_API_KEY to the user's shell startup file or the agent's documented env/secret configuration.

Do not paste the key into chat. Tell the user to replace the placeholder with their actual key from https://openrouter.ai/keys.

---

## Connect the OpenRouter MCP Server

If the current agent supports MCP, connect OpenRouter's remote MCP server so the agent can pull live model, pricing, credit, and usage data (and search the docs) while building. It is hosted by OpenRouter — nothing is installed locally — and authenticates over OAuth in the browser.

Add this server to the agent's MCP configuration:

```
https://mcp.openrouter.ai/mcp
```

Use the agent's native MCP setup where possible (for example, Claude Code: `claude mcp add --transport http openrouter https://mcp.openrouter.ai/mcp` then `claude mcp login openrouter`). If the agent does not support MCP, skip this step. For the full list of clients and tools, see https://openrouter.ai/docs/guides/overview/mcp-server.

---

## After Setup

Identify what the user is trying to build with OpenRouter.

If they already have a project or task, continue from there. If they have not given a task yet, suggest one concrete next step based on the current project and what you know about the user.

Include one concrete headless-agent idea using the create-headless-agent OpenRouter skill. The suggestion should be tailored to the user's project or recent requests.

End with a short summary:

- Which OpenRouter skills were installed
- Whether OPENROUTER_API_KEY is available, without revealing the value
- Whether the OpenRouter MCP server was connected (or skipped, if unsupported)
- Whether the user needs to restart or reload their agent
- The recommended next OpenRouter task