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
/**
* catalog.ts — single source of truth for the 46-entry Agent Skills catalog.
*
* Consumers: REST routes (/api/agent-skills/*), MCP tools, A2A skill, Generator.
* Do NOT import this from UI components directly — use the REST API instead.
*/
import fs from "node:fs";
import path from "node:path";
import type { AgentSkill, SkillCoverage, SkillMarkdown } from "./types";
import {
CURATED_SKILLS,
getAgentSkillRawUrl,
getAgentSkillBlobUrl,
} from "@/shared/constants/agentSkills";
// ── Canonical ID lists (D28) ────────────────────────────────────────────────
/** 23 canonical API skill IDs, in spec order. */
export const API_SKILL_IDS: readonly string[] = [
"omni-auth",
"omni-providers",
"omni-models",
"omni-combos-routing",
"omni-api-keys",
"omni-usage-logs",
"omni-budget",
"omni-settings",
"omni-proxies",
"omni-cache",
"omni-compression",
"omni-context-rtk",
"omni-resilience",
"omni-cli-tools",
"omni-tunnels",
"omni-sync-cloud",
"omni-db-backups",
"omni-webhooks",
"omni-mcp",
"omni-agents-a2a",
"omni-version-manager",
"omni-inference",
"omni-github-skills",
] as const;
/** Config skill IDs. */
export const CONFIG_SKILL_IDS: readonly string[] = ["config-codex-cli"] as const;
/** 21 canonical CLI skill IDs, in spec order. */
export const CLI_SKILL_IDS: readonly string[] = [
"cli-serve",
"cli-health",
"cli-providers",
"cli-keys",
"cli-models",
"cli-chat",
"cli-routing",
"cli-resilience",
"cli-compression",
"cli-contexts",
"cli-cost-usage",
"cli-mcp",
"cli-a2a",
"cli-tunnel",
"cli-backup-sync",
"cli-policy-audit",
"cli-batches",
"cli-eval",
"cli-plugins-skills",
"cli-setup",
"cli-skill-collector",
] as const;
// ── Module-scope cache ──────────────────────────────────────────────────────
let _cache: AgentSkill[] | null = null;
// ── Helpers ─────────────────────────────────────────────────────────────────
function buildFullSkill(curated: (typeof CURATED_SKILLS)[number]): AgentSkill {
return {
...curated,
endpoints: curated.category === "api" ? [] : undefined,
cliCommands: curated.category === "cli" ? [] : undefined,
rawUrl: getAgentSkillRawUrl(curated.id),
githubUrl: getAgentSkillBlobUrl(curated.id),
};
}
function deriveCatalog(): AgentSkill[] {
return CURATED_SKILLS.map(buildFullSkill);
}
// ── Public API ───────────────────────────────────────────────────────────────
/**
* Returns the full catalog (46 entries). Cached in module scope after first call.
* Safe to call multiple times — re-derives only after `refreshCatalog()`.
*/
export function getCatalog(): AgentSkill[] {
if (!_cache) {
_cache = deriveCatalog();
}
return _cache;
}
/** Returns single skill metadata or null. */
export function getSkillById(id: string): AgentSkill | null {
return getCatalog().find((s) => s.id === id) ?? null;
}
/** Filters catalog by category and/or area. */
export function filterCatalog(opts: {
category?: "api" | "cli" | "config";
area?: string;
}): AgentSkill[] {
let skills = getCatalog();
if (opts.category) {
skills = skills.filter((s) => s.category === opts.category);
}
if (opts.area) {
skills = skills.filter((s) => s.area === opts.area);
}
return skills;
}
/**
* Computes coverage stats: filesystem has SKILL.md vs the 46-entry catalog.
* Reads `skills/` relative to the project root (CWD).
*/
export function computeCoverage(): SkillCoverage {
const catalog = getCatalog();
const skillsDir = path.resolve(process.cwd(), "skills");
let presentIds: Set<string>;
try {
const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
presentIds = new Set(
entries
.filter((e) => e.isDirectory())
.filter((e) => fs.existsSync(path.join(skillsDir, e.name, "SKILL.md")))
.map((e) => e.name)
);
} catch {
// Directory doesn't exist yet — zero coverage
presentIds = new Set();
}
const apiHave = catalog.filter((s) => s.category === "api" && presentIds.has(s.id)).length;
const cliHave = catalog.filter((s) => s.category === "cli" && presentIds.has(s.id)).length;
const configTotal = CONFIG_SKILL_IDS.length;
const configHave = catalog.filter((s) => s.category === "config" && presentIds.has(s.id)).length;
return {
// Totals derive from the canonical id lists so catalog additions cannot
// leave the coverage contract behind.
api: { have: apiHave, total: API_SKILL_IDS.length },
cli: { have: cliHave, total: CLI_SKILL_IDS.length },
config: { have: configHave, total: configTotal },
totalSkills: apiHave + cliHave + configHave,
generatedAt: new Date().toISOString(),
};
}
/**
* Forces re-derivation of the catalog on next `getCatalog()` call.
* Used by tests and by the generator after writing new SKILL.md files.
*/
export function refreshCatalog(): void {
_cache = null;
}
/**
* Fetches the SKILL.md content for a given skill ID.
*
* Resolution order:
* 1. Local filesystem `skills/{id}/SKILL.md` (fast, used during dev + after generation)
* 2. GitHub raw URL with 1-hour cache (production fallback when file not yet generated)
*
* Returns a `SkillMarkdown` shape. Throws if both sources fail.
* Used by: F4 `/api/agent-skills/[id]/raw` route.
*/
export async function fetchSkillMarkdown(id: string): Promise<SkillMarkdown> {
const localPath = path.resolve(process.cwd(), "skills", id, "SKILL.md");
// 1. Try filesystem first
try {
const raw = fs.readFileSync(localPath, "utf-8");
const parsed = parseMarkdownFrontmatter(raw);
return {
id,
frontmatter: parsed.frontmatter,
body: parsed.body,
source: "filesystem",
fetchedAt: new Date().toISOString(),
};
} catch {
// File not present locally — fall through to GitHub
}
// 2. Fetch from GitHub raw (with Next.js revalidate cache if available)
const skill = getSkillById(id);
if (!skill) {
throw new Error(`Skill not found in catalog: ${id}`);
}
const response = await fetch(skill.rawUrl, {
next: { revalidate: 3600 },
} as unknown as RequestInit);
if (!response.ok) {
throw new Error(`GitHub raw fetch failed: HTTP ${response.status} for ${skill.rawUrl}`);
}
const raw = await response.text();
const parsed = parseMarkdownFrontmatter(raw);
return {
id,
frontmatter: parsed.frontmatter,
body: parsed.body,
source: "github",
fetchedAt: new Date().toISOString(),
};
}
// ── Internal helpers ─────────────────────────────────────────────────────────
/**
* Parses YAML frontmatter from a markdown string.
* Expects: `---\nkey: value\n---\n<body>` format.
* Returns default values if frontmatter is absent or malformed.
*/
function parseMarkdownFrontmatter(content: string): {
frontmatter: { name: string; description: string };
body: string;
} {
const FM_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
const match = FM_REGEX.exec(content);
if (!match) {
return {
frontmatter: { name: "", description: "" },
body: content,
};
}
const yamlBlock = match[1];
const body = match[2] ?? "";
// Simple key: value extraction (avoids importing js-yaml here to stay lightweight)
const nameMatch = /^name:\s*(.+)$/m.exec(yamlBlock);
const descMatch = /^description:\s*(.+)$/m.exec(yamlBlock);
return {
frontmatter: {
name: nameMatch ? nameMatch[1].trim().replace(/^["']|["']$/g, "") : "",
description: descMatch ? descMatch[1].trim().replace(/^["']|["']$/g, "") : "",
},
body,
};
}