Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
docs(agent-skills): add AGENT-SKILLS.md + cross-link in SKILLS.md
diegosouzapw712b00346ca6
diff --git a/docs/frameworks/AGENT-SKILLS.md b/docs/frameworks/AGENT-SKILLS.mdnew file mode 100644index 0000000000..79d8258eef--- /dev/null+++ b/docs/frameworks/AGENT-SKILLS.md@@ -0,0 +1,301 @@+---+title: "OmniRoute Agent Skills Catalog"+version: 3.8.6+lastUpdated: 2026-05-28+---++# OmniRoute Agent Skills Catalog++> **Source of truth:** `src/lib/agentSkills/` (catalog, generator, parsers) + `skills/` directory (SKILL.md files)+> **Last updated:** 2026-05-28 — v3.8.6++Agent Skills are structured SKILL.md files that teach external agents, MCP clients, and A2A orchestrators how to use OmniRoute's REST API and CLI. Unlike [Omni Skills](./SKILLS.md) (which are LLM tool definitions executed inside OmniRoute), Agent Skills are a *documentation catalog* — static markdown that can be fed directly into agent context.++---++## Overview++The catalog contains **42 canonical Agent Skills** (22 REST API + 20 CLI). Each skill has:++- A **canonical ID** (`omni-auth`, `cli-serve`, etc.)+- A **SKILL.md** file in `skills/{id}/SKILL.md` with YAML frontmatter (`name`, `description`) + rich markdown body+- **REST endpoints** (API skills) or **CLI subcommands** (CLI skills) derived from the OpenAPI spec and CLI registry+- A **GitHub raw URL** for live fetch: `https://raw.githubusercontent.com/diegosouzapw/OmniRoute/refs/heads/main/skills/{id}/SKILL.md`++---++## Architecture++```+src/shared/constants/agentSkills.ts — 42-entry curated list (name/desc/category/area/icon)+src/lib/agentSkills/+ catalog.ts — getCatalog(), getSkillById(), filterCatalog(), computeCoverage()+ generator.ts — generateAgentSkills() writes SKILL.md to skills/{id}/+ openapiParser.ts — extracts REST endpoints from docs/reference/openapi.yaml+ cliRegistryParser.ts — extracts CLI subcommands from bin/cli-registry.ts+ schemas.ts — Zod schemas: AgentSkillSchema, SkillCoverageSchema, etc.+ types.ts — TypeScript interfaces: AgentSkill, SkillCoverage, etc.++skills/{id}/SKILL.md — Generated + curated markdown files (42 total)++src/app/api/agent-skills/+ route.ts — GET /api/agent-skills+ [id]/route.ts — GET /api/agent-skills/{id}+ [id]/raw/route.ts — GET /api/agent-skills/{id}/raw (text/markdown)+ coverage/route.ts — GET /api/agent-skills/coverage+ generate/route.ts — POST /api/agent-skills/generate (auth required)++open-sse/mcp-server/tools/agentSkillTools.ts — 3 MCP tools (list, get, coverage)+src/lib/a2a/skills/listCapabilities.ts — A2A skill: list-capabilities+```++---++## SKILL.md Format++```markdown+---+name: omni-providers+description: "Manage provider connections: add, test, rotate, and remove credentials."+---+<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->++## Overview+...++## Authentication+...++## Endpoints+...++<!-- skill:custom-start -->+## Custom Section (preserved across regeneration)+...+<!-- skill:custom-end -->+```++The generator preserves content between `<!-- skill:custom-start -->` and `<!-- skill:custom-end -->` on regeneration. Ten skills have curated custom blocks:++`omni-mcp`, `omni-compression`, `cli-providers`, `cli-eval`, `omni-agents-a2a`, `omni-combos-routing`, `omni-auth`, `omni-resilience`, `omni-inference`, `cli-serve`.++---++## REST API Discovery++| Endpoint | Method | Description | Auth |+| :--- | :--- | :--- | :--- |+| `/api/agent-skills` | GET | List catalog (optional `?category=api\|cli&area=<area>`) | none |+| `/api/agent-skills/{id}` | GET | Get single skill metadata | none |+| `/api/agent-skills/{id}/raw` | GET | Fetch SKILL.md as `text/markdown` | none |+| `/api/agent-skills/coverage` | GET | Coverage stats (how many SKILL.md files exist) | none |+| `/api/agent-skills/generate` | POST | Trigger generator (dryRun/prune/onlyIds) | management |++Example — list all API skills:++```bash+curl "http://localhost:20128/api/agent-skills?category=api"+```++Example — fetch a single SKILL.md:++```bash+curl -H "Accept: text/markdown" "http://localhost:20128/api/agent-skills/omni-providers/raw"+```++---++## MCP Discovery++Three MCP tools are registered under scope `read:catalog`:++| Tool | Description |+| :--- | :--- |+| `omniroute_agent_skills_list` | List skills (optional `category` / `area` filters) |+| `omniroute_agent_skills_get` | Get metadata + SKILL.md for one skill by `id` |+| `omniroute_agent_skills_coverage` | Coverage stats (API/CLI have/total) |++See [MCP-SERVER.md](./MCP-SERVER.md) for scope wiring and authentication.++---++## A2A Discovery++The A2A skill `list-capabilities` returns the full 42-skill catalog as a markdown table artifact. External orchestrators can invoke it via:++```json+{+ "jsonrpc": "2.0", "id": "1",+ "method": "message/send",+ "params": {+ "skill": "list-capabilities",+ "messages": [{"role": "user", "content": "List all capabilities"}]+ }+}+```++See [A2A-SERVER.md](./A2A-SERVER.md) for protocol details.++---++## Catalog — 42 Skill IDs++### API Skills (22)++| ID | Area | Entry Point |+| :--- | :--- | :--- |+| `omni-auth` | auth | Auth + session management |+| `omni-providers` | providers | Provider connection management |+| `omni-models` | models | Model catalog and capabilities |+| `omni-combos-routing` | combos-routing | Combo routing strategies |+| `omni-api-keys` | api-keys | API key management |+| `omni-usage-logs` | usage-logs | Usage and cost logs |+| `omni-budget` | budget | Budget guards |+| `omni-settings` | settings | Global settings |+| `omni-proxies` | proxies | Proxy pool management |+| `omni-cache` | cache | Semantic + prompt cache |+| `omni-compression` | compression | Context compression engines |+| `omni-context-rtk` | context-rtk | RTK compression |+| `omni-resilience` | resilience | Circuit breakers + cooldowns |+| `omni-cli-tools` | cli-tools | CLI tools REST proxy |+| `omni-tunnels` | tunnels | Tunnel management |+| `omni-sync-cloud` | sync-cloud | Cloud sync |+| `omni-db-backups` | db-backups | Database backups |+| `omni-webhooks` | webhooks | Webhook event dispatcher |+| `omni-mcp` | mcp | MCP server (37 tools, 3 transports) |+| `omni-agents-a2a` | agents-a2a | A2A agent protocol |+| `omni-version-manager` | version-manager | Version and update management |+| `omni-inference` | inference | Direct inference / completions |++### CLI Skills (20)++| ID | Area | CLI Command Root |+| :--- | :--- | :--- |+| `cli-serve` | cli-serve | `omniroute serve` |+| `cli-health` | cli-health | `omniroute health` |+| `cli-providers` | cli-providers | `omniroute providers` |+| `cli-keys` | cli-keys | `omniroute keys` |+| `cli-models` | cli-models | `omniroute models` |+| `cli-chat` | cli-chat | `omniroute chat` |+| `cli-routing` | cli-routing | `omniroute routing` |+| `cli-resilience` | cli-resilience | `omniroute resilience` |+| `cli-compression` | cli-compression | `omniroute compression` |+| `cli-contexts` | cli-contexts | `omniroute contexts` |+| `cli-cost-usage` | cli-cost-usage | `omniroute cost` |+| `cli-mcp` | cli-mcp | `omniroute mcp` |+| `cli-a2a` | cli-a2a | `omniroute a2a` |+| `cli-tunnel` | cli-tunnel | `omniroute tunnel` |+| `cli-backup-sync` | cli-backup-sync | `omniroute backup` |+| `cli-policy-audit` | cli-policy-audit | `omniroute policy` |+| `cli-batches` | cli-batches | `omniroute batch` |+| `cli-eval` | cli-eval | `omniroute eval` |+| `cli-plugins-skills` | cli-plugins-skills | `omniroute plugins` |+| `cli-setup` | cli-setup | `omniroute setup` |++---++## How External Agents Consume Skills++### 1. Discovery via REST++```bash+# Get the full catalog+curl "http://your-omniroute/api/agent-skills" | jq '.skills[] | {id, name, category}'++# Get SKILL.md for context injection+curl "http://your-omniroute/api/agent-skills/omni-providers/raw" > omni-providers.md+```++### 2. Discovery via MCP++```typescript+// In a Claude Desktop / Cursor MCP client:+const result = await client.callTool("omniroute_agent_skills_list", { category: "api" });+// result.skills → array of AgentSkill with rawUrl for each+```++### 3. Discovery via A2A++```python+import requests++resp = requests.post("http://your-omniroute/a2a", json={+ "jsonrpc": "2.0", "id": "1",+ "method": "message/send",+ "params": {"skill": "list-capabilities", "messages": [{"role": "user", "content": "list"}]}+})+table = resp.json()["result"]["artifacts"][0]["content"]+# table is a markdown table with all 42 skill IDs + rawUrl columns+```++### 4. Direct GitHub raw fetch (no server required)++```bash+BASE="https://raw.githubusercontent.com/diegosouzapw/OmniRoute/refs/heads/main/skills"+curl "${BASE}/omni-providers/SKILL.md"+```++---++## Generator++The generator reads the curated catalog + OpenAPI spec + CLI registry and writes `skills/{id}/SKILL.md` for each entry:++```bash+# Preview (dry run, no writes)+curl -X POST http://localhost:20128/api/agent-skills/generate \+ -H "Authorization: Bearer <admin-key>" \+ -H "Content-Type: application/json" \+ -d '{"dryRun":true}'++# Full regeneration+curl -X POST http://localhost:20128/api/agent-skills/generate \+ -H "Authorization: Bearer <admin-key>" \+ -H "Content-Type: application/json" \+ -d '{"dryRun":false,"prune":false}'++# Regenerate specific IDs+curl -X POST http://localhost:20128/api/agent-skills/generate \+ -H "Authorization: Bearer <admin-key>" \+ -H "Content-Type: application/json" \+ -d '{"dryRun":false,"onlyIds":["omni-providers","cli-serve"]}'+```++The generator response is a `GeneratorReport`:++```json+{+ "generated": ["omni-providers", "cli-serve"],+ "unchanged": [],+ "pruned": [],+ "orphansDetected": [],+ "errors": []+}+```++---++## Coverage API++```bash+curl "http://localhost:20128/api/agent-skills/coverage"+```++```json+{+ "api": {"have": 22, "total": 22},+ "cli": {"have": 20, "total": 20},+ "totalSkills": 42,+ "generatedAt": "2026-05-28T00:00:00.000Z"+}+```++---++## Related++- [SKILLS.md](./SKILLS.md) — Omni Skills framework (LLM tool injection + marketplace)+- [MCP-SERVER.md](./MCP-SERVER.md) — MCP tool catalog (`omniroute_agent_skills_*` tools)+- [A2A-SERVER.md](./A2A-SERVER.md) — A2A protocol (`list-capabilities` skill)+- `src/lib/agentSkills/` — catalog, generator, parsers+- `skills/` — generated SKILL.md files (42 entries)diff --git a/docs/frameworks/SKILLS.md b/docs/frameworks/SKILLS.mdindex 313d8d82c1..748a842ca1 100644--- a/docs/frameworks/SKILLS.md+++ b/docs/frameworks/SKILLS.md@@ -1,13 +1,13 @@---title: "Skills Framework"-version: 3.8.2-lastUpdated: 2026-05-13+version: 3.8.6+lastUpdated: 2026-05-28---# Skills Framework> **Source of truth:** `src/lib/skills/` and `src/app/api/skills/`-> **Last updated:** 2026-05-13 — v3.8.0+> **Last updated:** 2026-05-28 — v3.8.6OmniRoute exposes an extensible Skills framework that lets language models (and operators) compose reusable capabilities — from filesystem reads and HTTP requests to sandboxed code execution and curated marketplace skills.@@ -15,6 +15,28 @@ A skill is a versioned, schema-defined unit of work. OmniRoute can inject skills---+## Agent Skills vs Omni Skills++OmniRoute has two distinct but complementary skill systems:++| Dimension | **Omni Skills** (this doc) | **Agent Skills** |+| :--- | :--- | :--- |+| Purpose | LLM tool injection + sandboxed execution | SKILL.md catalog for external agents to discover and consume |+| Source of truth | `src/lib/skills/` + marketplace | `src/lib/agentSkills/` + `skills/` directory |+| Runtime mode | Injected into outbound requests, executed on tool-call events | Static markdown catalog + REST/MCP/A2A discovery endpoints |+| Who uses it | OmniRoute itself (combo routing, inbound LLM calls) | External agents, MCP clients, A2A orchestrators |+| Count | Variable (marketplace-driven) | 42 canonical entries (22 API + 20 CLI) |+| Format | `SkillDefinition` with tool schema + handler | `SKILL.md` frontmatter + markdown body |+| Discovery | `/api/skills/*` REST + `omniroute_skills_*` MCP tools | `/api/agent-skills/*` REST + `omniroute_agent_skills_*` MCP tools + A2A `list-capabilities` |++**Omni Skills** are the execution engine — they define what OmniRoute *can do* when an LLM invokes a tool.++**Agent Skills** are the documentation catalog — they explain to external agents *how to use* OmniRoute's REST API and CLI, with structured SKILL.md files that can be fed directly into agent prompts.++For the Agent Skills catalog, generator, MCP tools, and A2A skill, see [docs/frameworks/AGENT-SKILLS.md](./AGENT-SKILLS.md).++---+## Concepts### Skill Sources