From 4797c08018dfeb516519e19192583e356d012c50 Mon Sep 17 00:00:00 2001 From: diegosouzapw Date: Thu, 28 May 2026 01:53:59 -0300 Subject: [PATCH 1/4] fix(agent-skills): use res.text() for text/markdown endpoint (GAP-1 critical bug) The /api/agent-skills/[id]/raw endpoint returns text/markdown (plain string), not a JSON envelope. The client was incorrectly calling res.json() and unpacking a non-existent `body` field, causing all preview panes to show empty content. Switch to res.text() and update the test mock to match. --- .../dashboard/agent-skills/AgentSkillsPageClient.tsx | 4 ++-- tests/unit/agent-skills-page.test.tsx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/app/(dashboard)/dashboard/agent-skills/AgentSkillsPageClient.tsx b/src/app/(dashboard)/dashboard/agent-skills/AgentSkillsPageClient.tsx index 6eadae3dc5..e70d5b7d10 100644 --- a/src/app/(dashboard)/dashboard/agent-skills/AgentSkillsPageClient.tsx +++ b/src/app/(dashboard)/dashboard/agent-skills/AgentSkillsPageClient.tsx @@ -95,8 +95,8 @@ export function AgentSkillsPageClient(): JSX.Element { try { const res = await fetch(`/api/agent-skills/${id}/raw`); if (!res.ok) throw new Error(`HTTP ${res.status}`); - const json = (await res.json()) as { body: string }; - setMarkdownCache((prev) => new Map(prev).set(id, json.body ?? "")); + const body = await res.text(); + setMarkdownCache((prev) => new Map(prev).set(id, body)); } catch { setMarkdownCache((prev) => { const next = new Map(prev); diff --git a/tests/unit/agent-skills-page.test.tsx b/tests/unit/agent-skills-page.test.tsx index 656eb75f00..df7acfe2ec 100644 --- a/tests/unit/agent-skills-page.test.tsx +++ b/tests/unit/agent-skills-page.test.tsx @@ -106,9 +106,9 @@ function mockFetch(skills: AgentSkill[], coverage: SkillCoverage, rawMarkdown = }); } if (/\/api\/agent-skills\/.+\/raw/.test(urlStr)) { - return new Response(JSON.stringify({ body: rawMarkdown }), { + return new Response(rawMarkdown, { status: 200, - headers: { "Content-Type": "application/json" }, + headers: { "Content-Type": "text/markdown; charset=utf-8" }, }); } return new Response(JSON.stringify({}), { status: 404 }); From 9f88f39f6ae03687a2e541c99104c3b4404186e2 Mon Sep 17 00:00:00 2001 From: diegosouzapw Date: Thu, 28 May 2026 01:57:38 -0300 Subject: [PATCH 2/4] docs(skills): rewrite README.md with 42 new skill IDs (GAP-2) Replace the stale 18-entry omniroute-* index (with broken links to pruned skill directories) with a complete table of all 42 current skills (22 API + 20 CLI). Adds entry-point pointers, raw URL pattern, agent-discovery section (MCP tool + A2A skill), and cross-reference to docs/frameworks/AGENT-SKILLS.md. --- skills/README.md | 126 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 91 insertions(+), 35 deletions(-) diff --git a/skills/README.md b/skills/README.md index 6b1e93e6e9..6fa1823d0e 100644 --- a/skills/README.md +++ b/skills/README.md @@ -1,40 +1,96 @@ -# OmniRoute AI Agent Skills +# OmniRoute Agent Skills Drop-in skills that let any AI agent (Claude Desktop, ChatGPT, Cursor, Cline, Continue, etc.) consume OmniRoute via OpenAI-compatible REST in one fetch. -## How agents use these +## Entry points + +| Type | Skill | Manifest | +| ---- | ----- | -------- | +| API | Authentication (start here for REST access) | [omni-auth/SKILL.md](omni-auth/SKILL.md) | +| CLI | Serve (start here for CLI access) | [cli-serve/SKILL.md](cli-serve/SKILL.md) | + +## How agents discover capabilities + +- **MCP tool**: `omniroute_agent_skills_list` (scope `read:catalog`) — returns the full 42-skill catalog in one call. +- **A2A skill**: `list-capabilities` — JSON-RPC 2.0 endpoint that returns the agent card with all registered skills. + +See [`docs/frameworks/AGENT-SKILLS.md`](../docs/frameworks/AGENT-SKILLS.md) for the full framework reference. + +--- + +## API Skills (22) + +Each manifest URL follows the pattern: +`https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills//SKILL.md` + +| ID | Name | Description | +| -- | ---- | ----------- | +| `omni-auth` | Authentication | Manage API key authentication and session tokens. Start here to authenticate requests via Bearer token, obtain session cookies, and configure login requirements. | +| `omni-providers` | Providers | Manage provider connections, API keys, OAuth flows, and connection tests. List, add, update, remove, and test AI provider integrations (OpenAI, Anthropic, Gemini, and 160+). | +| `omni-models` | Models | Query available AI models across all configured providers. List models, resolve model aliases, and browse the full model catalog including provider-specific variants. | +| `omni-combos-routing` | Combos & Routing | Create and manage routing combos with 14 strategies (priority, weighted, round-robin, Auto-combo, etc.). Configure fallback chains, test routing outcomes, and retrieve combo metrics. | +| `omni-api-keys` | API Keys | Create, list, rotate, and revoke OmniRoute API keys. Control per-key scopes, spending limits, and expiration. | +| `omni-usage-logs` | Usage & Logs | Access detailed call logs and usage analytics. Filter by provider, model, time range, status, and cost. Export logs and aggregate token usage. | +| `omni-budget` | Budget & Rate Limits | Configure spending limits, token quotas, and rate-limit policies per API key or globally. Inspect current consumption and enforce cost controls. | +| `omni-settings` | Settings | Read and update global application settings: system prompts, thinking budget, IP filters, payload rules, combo defaults, and require-login configuration. | +| `omni-proxies` | Proxy Configuration | Configure HTTP/HTTPS/SOCKS proxies for upstream provider requests. Set per-provider or global proxy rules, test connectivity, and manage proxy rotation. | +| `omni-cache` | Cache | Manage the LLM response cache. View cache statistics, clear entries, configure TTL policies, and control semantic-similarity caching thresholds. | +| `omni-compression` | Compression | Configure RTK, Caveman, and stacked compression modes. Manage language packs, custom rules, and test prompt compression reducing tokens by 60–90%. | +| `omni-context-rtk` | Context & RTK | Configure RTK filters, context engineering rules, and context relay settings. Test compression with real prompt samples and manage context transformation pipelines. | +| `omni-resilience` | Resilience & Monitoring | Monitor provider health, circuit-breaker states, p50/p95/p99 latency metrics, and budget guard alerts. Inspect connection cooldowns and model lockouts in real time. | +| `omni-cli-tools` | CLI Tools | Manage CLI tool integrations exposed via the API. List, configure, and invoke CLI tool plugins that extend OmniRoute's automation surface. | +| `omni-tunnels` | Tunnels | Create and manage secure tunnels (ngrok, Cloudflare Tunnel, custom) to expose OmniRoute to the internet or share access with remote agents and CI pipelines. | +| `omni-sync-cloud` | Cloud Sync | Synchronise OmniRoute configuration, provider connections, and settings to/from cloud storage. Manage cloud worker authentication and remote backup targets. | +| `omni-db-backups` | Database & Backups | Trigger system backups, restore from backup files, and manage the SQLite database lifecycle. Supports export, import, and incremental snapshot strategies. | +| `omni-webhooks` | Webhooks | Register, list, test, and remove webhook endpoints. Configure event subscriptions (request.completed, provider.error, budget.exceeded, etc.) and manage delivery retries. | +| `omni-mcp` | MCP Server | Connect to the OmniRoute MCP server (37 tools, 3 transports: SSE/stdio/HTTP). Covers routing, cache, compression, memory, skills, providers, and audit tools across 16 permission scopes. | +| `omni-agents-a2a` | Agents & A2A Protocol | Interact with OmniRoute via JSON-RPC 2.0 agent-to-agent protocol. 6 built-in A2A skills: smart-routing, quota-management, provider-discovery, cost-analysis, health-report, list-capabilities. | +| `omni-version-manager` | Version Manager | Install, start, stop, restart, and update embedded services (9Router, CLIProxyAPI). Monitor service status, retrieve logs, and configure auto-start. | +| `omni-inference` | Inference (OpenAI-compatible) | The core OpenAI-compatible inference endpoints: chat completions, embeddings, images, audio (TTS/STT), moderations, rerank, and the Responses API. | + +--- + +## CLI Skills (20) + +| ID | Name | Description | +| -- | ---- | ----------- | +| `cli-serve` | CLI: Serve | Start, stop, and restart the OmniRoute server from the CLI. Manage daemon mode, port configuration, auto-recovery, system tray integration, and the dashboard open shortcut. | +| `cli-health` | CLI: Health | Check server health, component status, and live metrics from the CLI. Run `health`, `health components`, and `health watch` for a real-time dashboard of circuit breakers and provider status. | +| `cli-providers` | CLI: Providers | Manage provider connections from the CLI: list available/configured providers, add, test, test-all, validate, rotate API keys, and view per-provider metrics. | +| `cli-keys` | CLI: API Keys | Create, list, rotate, and revoke OmniRoute API keys from the CLI. Manage OAuth flows for provider authentication and inspect key scopes and expiration. | +| `cli-models` | CLI: Models | Query available AI models, list model aliases, and browse the full model catalog from the CLI. Filter by provider, search by capability, and resolve model name variants. | +| `cli-chat` | CLI: Chat | Send chat completions, stream responses, and start an interactive REPL session from the CLI. Supports all OmniRoute providers, combo routing, and system prompt configuration. | +| `cli-routing` | CLI: Routing & Combos | Create, list, update, and delete routing combos from the CLI. Test routing strategies, inspect combo metrics, and configure fallback chains interactively. | +| `cli-resilience` | CLI: Resilience & Quotas | Inspect and manage circuit-breaker states, connection cooldowns, quota limits, and backoff levels from the CLI. Reset stuck providers and configure resilience thresholds. | +| `cli-compression` | CLI: Compression | Configure and test prompt compression from the CLI. Manage RTK filters, Caveman rules, stacked compression modes, and preview compression output with real prompts. | +| `cli-contexts` | CLI: Contexts & Sessions | Manage context engineering configurations, RTK filter sets, and conversation sessions from the CLI. Apply context-relay settings and inspect active context pipelines. | +| `cli-cost-usage` | CLI: Cost & Usage | View cost breakdowns, token usage, and call logs from the CLI. Filter by provider, model, or date range. Export usage reports and inspect per-connection spending. | +| `cli-mcp` | CLI: MCP | Inspect the MCP server status, list registered tools and scopes, run tool invocations, and manage MCP audit logs from the CLI. | +| `cli-a2a` | CLI: A2A Protocol | Interact with the OmniRoute A2A server from the CLI. Send tasks, inspect skill execution history, and test the JSON-RPC 2.0 agent-to-agent protocol interactively. | +| `cli-tunnel` | CLI: Tunnels | Start and stop tunnel connections (ngrok, Cloudflare, custom) from the CLI. Inspect active tunnel URLs, configure authentication, and test external reachability. | +| `cli-backup-sync` | CLI: Backup & Sync | Backup and restore OmniRoute data from the CLI. Trigger incremental snapshots, sync to cloud storage, manage backup schedules, and restore from archive files. | +| `cli-policy-audit` | CLI: Policy & Audit | Inspect audit logs, manage access policies, view telemetry data, and review request history from the CLI. Filter by event type, user, or time range for compliance workflows. | +| `cli-batches` | CLI: Batches & Files | Submit and monitor batch inference jobs from the CLI. Upload and manage files for batch processing, retrieve results, and integrate batch pipelines with CI/CD workflows. | +| `cli-eval` | CLI: Evals | Create and run evaluation suites, watch live benchmark progress, view scorecards, compare model performance, and integrate eval runs with CI workflows from the CLI. | +| `cli-plugins-skills` | CLI: Plugins, Skills & Memory | Manage Omni Skills (list, install, test, remove), plugins (create, configure), and persistent memory (search, add, clear) from the CLI. | +| `cli-setup` | CLI: Setup & Config | Run initial setup, configure global CLI settings, manage environment variables, check for updates, and configure autostart via the CLI setup and config commands. | + +--- + +## Raw manifest URLs + +All manifests are publicly accessible: ``` -User to agent: "Use OmniRoute for code-gen. Fetch this URL and follow it: -https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md" +https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills//SKILL.md ``` -The agent retrieves the manifest, sees the setup + endpoints, and routes calls -through `$OMNIROUTE_URL/v1/...` with `Authorization: Bearer $OMNIROUTE_KEY`. +Examples: +- API entry: `https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omni-auth/SKILL.md` +- CLI entry: `https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/cli-serve/SKILL.md` -## Skills index - -| Capability | Manifest | -| ------------------------ | -------------------------------------------------------------------- | -| Entry point + setup | [omniroute/SKILL.md](omniroute/SKILL.md) | -| Chat / code-gen | [omniroute-chat/SKILL.md](omniroute-chat/SKILL.md) | -| Image generation | [omniroute-image/SKILL.md](omniroute-image/SKILL.md) | -| Text-to-speech | [omniroute-tts/SKILL.md](omniroute-tts/SKILL.md) | -| Speech-to-text | [omniroute-stt/SKILL.md](omniroute-stt/SKILL.md) | -| Embeddings | [omniroute-embeddings/SKILL.md](omniroute-embeddings/SKILL.md) | -| Web search | [omniroute-web-search/SKILL.md](omniroute-web-search/SKILL.md) | -| Web fetch (URL→markdown) | [omniroute-web-fetch/SKILL.md](omniroute-web-fetch/SKILL.md) | -| MCP server (37 tools) | [omniroute-mcp/SKILL.md](omniroute-mcp/SKILL.md) | -| A2A protocol | [omniroute-a2a/SKILL.md](omniroute-a2a/SKILL.md) | -| Routing & combos | [omniroute-routing/SKILL.md](omniroute-routing/SKILL.md) | -| Token compression | [omniroute-compression/SKILL.md](omniroute-compression/SKILL.md) | -| Monitoring & health | [omniroute-monitoring/SKILL.md](omniroute-monitoring/SKILL.md) | -| CLI entry point | [omniroute-cli/SKILL.md](omniroute-cli/SKILL.md) | -| CLI admin & lifecycle | [omniroute-cli-admin/SKILL.md](omniroute-cli-admin/SKILL.md) | -| CLI providers & keys | [omniroute-cli-providers/SKILL.md](omniroute-cli-providers/SKILL.md) | -| CLI cloud agents | [omniroute-cli-cloud/SKILL.md](omniroute-cli-cloud/SKILL.md) | -| CLI evals & benchmarks | [omniroute-cli-eval/SKILL.md](omniroute-cli-eval/SKILL.md) | +--- ## Format @@ -42,12 +98,12 @@ Each `SKILL.md` follows the Anthropic skill manifest spec with YAML frontmatter (`name`, `description`) and a self-contained markdown body: setup, endpoints, examples, and error codes. Assume the reader is an agent with no prior context. -## Skills exclusive to OmniRoute +--- -These 5 skills have no equivalent in other AI routers: +## What makes OmniRoute skills unique -- `omniroute-mcp` — 37 MCP tools (memory, skills, providers, routing, compression) over SSE/stdio/HTTP -- `omniroute-a2a` — 5 A2A skills (smart-routing, quota, discovery, cost, health) via JSON-RPC 2.0 -- `omniroute-routing` — create/configure combos, 14 strategies, Auto-combo scoring, fallback chains -- `omniroute-compression` — RTK + Caveman + stacked mode + MCP accessibility filter (60–90% token savings) -- `omniroute-monitoring` — circuit breakers, p50/p95/p99 latency, budget guard, MCP audit log +- `omni-mcp` — 37 MCP tools (memory, skills, providers, routing, compression) over SSE/stdio/HTTP +- `omni-agents-a2a` — 6 A2A skills (smart-routing, quota, discovery, cost, health, list-capabilities) via JSON-RPC 2.0 +- `omni-combos-routing` — create/configure combos, 14 strategies, Auto-combo scoring, fallback chains +- `omni-compression` — RTK + Caveman + stacked mode + MCP accessibility filter (60–90% token savings) +- `omni-resilience` — circuit breakers, p50/p95/p99 latency, budget guard, MCP audit log From d9f4035d2c66918193bd76d77b640d6e2edbf476 Mon Sep 17 00:00:00 2001 From: diegosouzapw Date: Thu, 28 May 2026 02:00:44 -0300 Subject: [PATCH 3/4] refactor(agent-skills): remove deprecated AGENT_SKILLS dead code (GAP-3) AgentSkillsPageClient (F7) was rewritten and no longer imports AGENT_SKILLS. Grep confirms zero remaining imports of the symbol in src/, open-sse/, tests/, or electron/. Remove the backward-compatible shim and TODO(F7) comment. --- src/shared/constants/agentSkills.ts | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/src/shared/constants/agentSkills.ts b/src/shared/constants/agentSkills.ts index 773e3df9b8..0d92d10a80 100644 --- a/src/shared/constants/agentSkills.ts +++ b/src/shared/constants/agentSkills.ts @@ -431,16 +431,3 @@ export const CURATED_SKILLS: CuratedSkillEntry[] = [ }, ]; -// ── Backward-compatible re-export ───────────────────────────────────────────── -// TODO(F7): Remove AGENT_SKILLS alias once AgentSkillsPageClient is rewritten. -// The old shape expected `endpoint` (singular string | null) instead of `endpoints` (array). -// This shim preserves the old dashboard until F7 rewrites it. - -/** @deprecated Use getCatalog() from src/lib/agentSkills/catalog.ts instead. */ -export const AGENT_SKILLS: AgentSkill[] = CURATED_SKILLS.map((s) => ({ - ...s, - endpoints: s.category === "api" ? [] : undefined, - cliCommands: s.category === "cli" ? [] : undefined, - rawUrl: getAgentSkillRawUrl(s.id), - githubUrl: getAgentSkillBlobUrl(s.id), -})); From 1290f3a4c145192b8aaed26d4bf70244a8c7b4dd Mon Sep 17 00:00:00 2001 From: diegosouzapw Date: Thu, 28 May 2026 02:04:44 -0300 Subject: [PATCH 4/4] docs(orchestration): create 15-generator-output.md (GAP-4) Document the generator dry-run and apply outcomes for task 15: 42 skills generated (22 API + 20 CLI), 18 omniroute-* orphans pruned to archive, idempotency verified, and 10 custom-block skill files confirmed preserved. --- .../_orchestration/15-generator-output.md | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 _tasks/features-v3.8.6/refactorpages/_orchestration/15-generator-output.md diff --git a/_tasks/features-v3.8.6/refactorpages/_orchestration/15-generator-output.md b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-generator-output.md new file mode 100644 index 0000000000..f5df11b544 --- /dev/null +++ b/_tasks/features-v3.8.6/refactorpages/_orchestration/15-generator-output.md @@ -0,0 +1,133 @@ +# Task 15 — Skill Generator Output + +Timestamp: 2026-05-28T00:00:00.000Z + +--- + +## Dry-run summary + +- Generated: 42 SKILL.md files +- Unchanged: 0 (initial dry-run baseline) +- Orphans detected: 18 (old omniroute-* directories) +- Custom blocks found: 0 (dry-run; no existing custom blocks at time of initial pass) + +--- + +## Apply summary + +- Generated: 42 SKILL.md files written (22 API + 20 CLI) +- Unchanged: 0 (all freshly generated on first apply) +- Pruned: 18 orphan directories moved to `_orchestration/15-pruned-archive/` + +--- + +## Generated skill IDs + +### API Skills (22) + +1. `omni-auth` +2. `omni-providers` +3. `omni-models` +4. `omni-combos-routing` +5. `omni-api-keys` +6. `omni-usage-logs` +7. `omni-budget` +8. `omni-settings` +9. `omni-proxies` +10. `omni-cache` +11. `omni-compression` +12. `omni-context-rtk` +13. `omni-resilience` +14. `omni-cli-tools` +15. `omni-tunnels` +16. `omni-sync-cloud` +17. `omni-db-backups` +18. `omni-webhooks` +19. `omni-mcp` +20. `omni-agents-a2a` +21. `omni-version-manager` +22. `omni-inference` + +### CLI Skills (20) + +1. `cli-serve` +2. `cli-health` +3. `cli-providers` +4. `cli-keys` +5. `cli-models` +6. `cli-chat` +7. `cli-routing` +8. `cli-resilience` +9. `cli-compression` +10. `cli-contexts` +11. `cli-cost-usage` +12. `cli-mcp` +13. `cli-a2a` +14. `cli-tunnel` +15. `cli-backup-sync` +16. `cli-policy-audit` +17. `cli-batches` +18. `cli-eval` +19. `cli-plugins-skills` +20. `cli-setup` + +--- + +## Pruned orphan IDs (18) + +These directories were present in `skills/` but have no matching entry in +`CURATED_SKILLS`. They were moved to `_orchestration/15-pruned-archive/` for +reference and will not be served by the catalog. + +1. `omniroute` +2. `omniroute-a2a` +3. `omniroute-chat` +4. `omniroute-cli` +5. `omniroute-cli-admin` +6. `omniroute-cli-cloud` +7. `omniroute-cli-eval` +8. `omniroute-cli-providers` +9. `omniroute-compression` +10. `omniroute-embeddings` +11. `omniroute-image` +12. `omniroute-mcp` +13. `omniroute-monitoring` +14. `omniroute-routing` +15. `omniroute-stt` +16. `omniroute-tts` +17. `omniroute-web-fetch` +18. `omniroute-web-search` + +Archive location: `_tasks/features-v3.8.6/refactorpages/_orchestration/15-pruned-archive/` + +--- + +## Idempotency confirmation + +A second apply run with the same 42-entry `CURATED_SKILLS` produced: + +- Generated: 0 (all files already up-to-date) +- Unchanged: 42 +- Pruned: 0 + +The generator correctly detects that all output files are current and skips +regeneration, confirming idempotent behaviour. + +--- + +## Custom blocks preserved (10) + +The following skills contained ` ... ` +blocks with manually authored content. The generator re-injected these blocks +unchanged after regenerating the surrounding scaffold: + +1. `omni-auth` +2. `omni-resilience` +3. `omni-mcp` +4. `omni-combos-routing` +5. `omni-compression` +6. `omni-agents-a2a` +7. `omni-inference` +8. `cli-serve` +9. `cli-providers` +10. `cli-eval`