OmniRoute/docs/frameworks/AGENT-SKILLS.md

title, version, lastUpdated

title	version	lastUpdated
OmniRoute Agent Skills Catalog	3.8.6	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 (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/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

---
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:

curl "http://localhost:20128/api/agent-skills?category=api"

Example — fetch a single SKILL.md:

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 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:

{
  "jsonrpc": "2.0", "id": "1",
  "method": "message/send",
  "params": {
    "skill": "list-capabilities",
    "messages": [{"role": "user", "content": "List all capabilities"}]
  }
}

See 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 (87 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

# 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

// 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

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)

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:

# 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:

{
  "generated": ["omni-providers", "cli-serve"],
  "unchanged": [],
  "pruned": [],
  "orphansDetected": [],
  "errors": []
}

---

Coverage API

curl "http://localhost:20128/api/agent-skills/coverage"

{
  "api": {"have": 22, "total": 22},
  "cli": {"have": 20, "total": 20},
  "totalSkills": 42,
  "generatedAt": "2026-05-28T00:00:00.000Z"
}

---

Related

• SKILLS.md — Omni Skills framework (LLM tool injection + marketplace)
• MCP-SERVER.md — MCP tool catalog (omniroute_agent_skills_* tools)
• A2A-SERVER.md — A2A protocol (list-capabilities skill)
• src/lib/agentSkills/ — catalog, generator, parsers
• skills/ — generated SKILL.md files (42 entries)