> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent-mintlify-f21cea86.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Teaching custom routes

> Teach Arka phrase-to-skill mappings that persist across sessions — correct routing mistakes, add shortcuts, and manage learned routes.

Arka can learn **persistent natural-language routes**: phrase → skill mappings stored in `~/.config/arka/learned_routes.json`. The router checks learned routes early, before symbolic rules.

## Teach a route

```bash theme={null}
arka route_learn learn "deploy staging" "agent_code run deploy.sh"
arka route_learn learn "my dashboard" system_monitor
```

Natural language:

```bash theme={null}
arka teach route "deploy staging" to "agent_code run deploy.sh"
arka learn that when I say "morning standup" means stock news
arka remember route "check disk" as disk_breakdown
```

## Correct a routing mistake

After a request routes incorrectly, fix it from the last trace:

```bash theme={null}
arka route_learn learn --from-trace --correct "stock news"
```

This pairs the trace input with the skill you intended.

## Manage routes

| Command | Description |
| - | - |
| `arka route_learn list` | List all learned routes |
| `arka route_learn delete <id-or-phrase>` | Remove a route |
| `arka route_learn test <phrase>` | Preview what a phrase would run |

Natural language:

```bash theme={null}
arka list learned routes
```

## Placeholders

Use `{args}` in the skill line to capture trailing text:

```bash theme={null}
arka route_learn learn "summarize repo" "github_repo activity {args}"
# "summarize repo Sumit884-byte/arka" → github_repo activity Sumit884-byte/arka
```

## How matching works

* Exact trigger matches run the skill line as-is.
* Prefix matches append the remainder (`"check servers in prod"` → `system_monitor in prod`).
* Longer triggers win over shorter ones.

<Tip>
  Learned routes use zero LLM tokens. They are ideal for team-specific shortcuts and correcting recurring misroutes.
</Tip>

## Related

* [Routing concepts](/concepts/routing) — symbolic rules and LLM fallback
* [CLI reference](/guides/cli) — `route_learn` subcommands


## Related topics

- [Arka CLI command and flag reference](/guides/cli.md)
- [AI agent guide — use Arka over MCP](/guides/ai-agents.md)
- [GitHub dataset repos](/guides/github-dataset.md)
- [Skills catalog: 70+ built-in Arka commands](/guides/skills.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.