diff --git a/docs/frameworks/AGENT-SKILLS.md b/docs/frameworks/AGENT-SKILLS.md
new file mode 100644
index 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."
+---
+
+
+## Overview
+...
+
+## Authentication
+...
+
+## Endpoints
+...
+
+
+## Custom Section (preserved across regeneration)
+...
+
+```
+
+The generator preserves content between `` and `` 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=`) | 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 " \
+ -H "Content-Type: application/json" \
+ -d '{"dryRun":true}'
+
+# Full regeneration
+curl -X POST http://localhost:20128/api/agent-skills/generate \
+ -H "Authorization: Bearer " \
+ -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 " \
+ -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.md
index 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.6
OmniRoute 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