Skip to content

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

feat(agent-skills): add generator with idempotent skill md generation + prune

diegosouzapwf86e905efbdc
diff --git a/src/lib/agentSkills/generator.ts b/src/lib/agentSkills/generator.ts
new file mode 100644
index 0000000000..5df831edfa
--- /dev/null
+++ b/src/lib/agentSkills/generator.ts
@@ -0,0 +1,365 @@
+/**
+ * generator.ts — idempotent SKILL.md generator for all 42 agent skills.
+ *
+ * Usage (library):
+ * import { generateAgentSkills, buildSkillMarkdown } from "@/lib/agentSkills/generator";
+ *
+ * Usage (CLI):
+ * node scripts/skills/generate-agent-skills.mjs [--apply] [--prune] [--only=id1,id2] [--json]
+ *
+ * Safety contract:
+ * - Default: dryRun=true, prune=false (no filesystem writes).
+ * - dryRun=false is required for any actual writes.
+ * - prune=true AND dryRun=false is required to delete orphan directories.
+ * - F9 is responsible for running apply; F3 only implements + tests the generator.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getCatalog, refreshCatalog } from "./catalog";
+import { parseOpenapi } from "./openapiParser";
+import { parseCliRegistry } from "./cliRegistryParser";
+import type { AgentSkill, GeneratorOptions, GeneratorReport } from "./types";
+import type { ParsedOpenapi } from "./openapiParser";
+import type { ParsedCliRegistry } from "./cliRegistryParser";
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const GENERATED_COMMENT =
+ "<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->";
+
+const CUSTOM_START_MARKER = "<!-- skill:custom-start -->";
+const CUSTOM_END_MARKER = "<!-- skill:custom-end -->";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+interface BuildSources {
+ openapi: ParsedOpenapi;
+ cliRegistry: ParsedCliRegistry;
+}
+
+// ── Frontmatter helpers ───────────────────────────────────────────────────────
+
+/**
+ * Serializes frontmatter to YAML front-matter block.
+ * Handles descriptions with colons or special characters safely.
+ */
+function serializeFrontmatter(fm: { name: string; description: string }): string {
+ // Use block scalar for description if it contains colons, quotes, or newlines
+ const needsQuote = (v: string): boolean => /[:\n"']/.test(v) || v.startsWith(" ");
+
+ const nameStr = needsQuote(fm.name) ? `"${fm.name.replace(/"/g, '\\"')}"` : fm.name;
+ const descStr = needsQuote(fm.description)
+ ? `"${fm.description.replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`
+ : fm.description;
+
+ return `---\nname: ${nameStr}\ndescription: ${descStr}\n---\n`;
+}
+
+/**
+ * Extracts the custom block content from an existing SKILL.md string.
+ * Returns null if no custom block is found.
+ */
+function extractCustomBlock(content: string): string | null {
+ const startIdx = content.indexOf(CUSTOM_START_MARKER);
+ const endIdx = content.indexOf(CUSTOM_END_MARKER);
+ if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) return null;
+ return content.slice(startIdx, endIdx + CUSTOM_END_MARKER.length);
+}
+
+// ── Body builders ─────────────────────────────────────────────────────────────
+
+function buildApiBody(skill: AgentSkill, sources: BuildSources): string {
+ const areaMap = sources.openapi.areas;
+ const ops = areaMap.get(skill.area as Parameters<typeof areaMap.get>[0]) ?? [];
+
+ const lines: string[] = [];
+
+ lines.push("## Visão geral\n");
+ lines.push(skill.description);
+ lines.push("");
+
+ lines.push("## Autenticação\n");
+ lines.push(
+ "All requests require a valid Bearer token or session cookie. " +
+ "Obtain a token via `POST /api/auth/login` or configure `REQUIRE_API_KEY=false` for local development.",
+ );
+ lines.push("");
+
+ lines.push("## Endpoints\n");
+
+ if (ops.length === 0) {
+ lines.push("_No endpoints mapped for this area yet._");
+ } else {
+ for (const op of ops) {
+ lines.push(`### ${op.method} ${op.path}\n`);
+ if (op.summary) {
+ lines.push(`${op.summary}`);
+ lines.push("");
+ }
+ if (op.description) {
+ lines.push(op.description);
+ lines.push("");
+ }
+ // Minimal curl example
+ const curlMethod = op.method === "GET" ? "" : `-X ${op.method} `;
+ lines.push("```bash");
+ lines.push(
+ `curl ${curlMethod}https://localhost:20128${op.path} \\`,
+ );
+ lines.push(' -H "Authorization: Bearer $OMNIROUTE_TOKEN"');
+ if (["POST", "PUT", "PATCH"].includes(op.method)) {
+ lines.push(' -H "Content-Type: application/json" \\');
+ lines.push(" -d '{}'");
+ }
+ lines.push("```");
+ lines.push("");
+ }
+ }
+
+ lines.push("## Payloads\n");
+ lines.push(
+ "See the full OpenAPI specification at `GET /api/openapi/spec` or " +
+ "`docs/reference/openapi.yaml` for detailed request/response schemas.",
+ );
+ lines.push("");
+
+ return lines.join("\n");
+}
+
+function buildCliBody(skill: AgentSkill, sources: BuildSources): string {
+ const familyMap = sources.cliRegistry.families;
+ const cmds =
+ familyMap.get(skill.area as Parameters<typeof familyMap.get>[0]) ?? [];
+
+ const lines: string[] = [];
+
+ lines.push("## Visão geral\n");
+ lines.push(skill.description);
+ lines.push("");
+
+ lines.push("## Instalação rápida\n");
+ lines.push("```bash");
+ lines.push("npm install -g omniroute # or: npx omniroute");
+ lines.push("omniroute --version");
+ lines.push("```");
+ lines.push("");
+
+ lines.push("## Subcomandos\n");
+
+ if (cmds.length === 0) {
+ lines.push("_No CLI subcommands mapped for this family yet._");
+ lines.push("");
+ } else {
+ for (const cmd of cmds) {
+ lines.push(`### \`${cmd.name}\`\n`);
+ if (cmd.description) {
+ lines.push(cmd.description);
+ lines.push("");
+ }
+
+ if (cmd.flags.length > 0) {
+ lines.push("**Flags:**\n");
+ for (const flag of cmd.flags) {
+ lines.push(`- \`${flag}\``);
+ }
+ lines.push("");
+ }
+
+ lines.push("**Exemplo:**\n");
+ lines.push("```bash");
+ lines.push(`omniroute ${cmd.name}`);
+ lines.push("```");
+ lines.push("");
+ }
+ }
+
+ return lines.join("\n");
+}
+
+// ── Core builder ─────────────────────────────────────────────────────────────
+
+/**
+ * Generates the full SKILL.md string (frontmatter + comment + body) for a given skill.
+ *
+ * If `existingContent` is provided, any `<!-- skill:custom-start --> ... <!-- skill:custom-end -->`
+ * block found in it is re-injected after the generated body (marker preservation / D24).
+ */
+export function buildSkillMarkdown(
+ skillId: string,
+ sources: BuildSources,
+ existingContent?: string,
+): { frontmatter: { name: string; description: string }; body: string } {
+ const skill = getCatalog().find((s) => s.id === skillId);
+ if (!skill) {
+ throw new Error(`buildSkillMarkdown: skill "${skillId}" not found in catalog`);
+ }
+
+ const fm = {
+ name: skill.id,
+ description: skill.description.slice(0, 2000),
+ };
+
+ const bodyLines =
+ skill.category === "api"
+ ? buildApiBody(skill, sources)
+ : buildCliBody(skill, sources);
+
+ // Re-inject custom block if present in existing content
+ let customBlock = "";
+ if (existingContent) {
+ const extracted = extractCustomBlock(existingContent);
+ if (extracted) {
+ customBlock = `\n${extracted}\n`;
+ }
+ }
+
+ const body =
+ GENERATED_COMMENT +
+ "\n\n" +
+ bodyLines +
+ customBlock;
+
+ return { frontmatter: fm, body };
+}
+
+/**
+ * Assembles the full file content string from frontmatter + body.
+ */
+function assembleFileContent(fm: { name: string; description: string }, body: string): string {
+ return serializeFrontmatter(fm) + body;
+}
+
+// ── Main generator ─────────────────────────────────────────────────────────────
+
+/**
+ * Runs the full generator. Idempotent.
+ *
+ * - dryRun=true (default): returns report but writes nothing to disk.
+ * - dryRun=false: writes/updates SKILL.md files as needed.
+ * - prune=true: detects orphan directories in `skills/` not in the catalog.
+ * - dryRun=true + prune=true: lists orphans, no deletions.
+ * - dryRun=false + prune=true: deletes orphan directories.
+ */
+export async function generateAgentSkills(opts: GeneratorOptions): Promise<GeneratorReport> {
+ const { dryRun = true, prune = false, outputDir = "skills", onlyIds } = opts;
+
+ const outputBase = path.resolve(process.cwd(), outputDir);
+
+ const catalog = getCatalog();
+ const catalogIds = new Set(catalog.map((s) => s.id));
+
+ // Filter to onlyIds if provided
+ const skillsToProcess = onlyIds
+ ? catalog.filter((s) => onlyIds.includes(s.id))
+ : catalog;
+
+ // Lazily parse sources (only once per generator run)
+ let _openapi: ParsedOpenapi | null = null;
+ let _cliRegistry: ParsedCliRegistry | null = null;
+
+ function getSources(): BuildSources {
+ if (!_openapi) {
+ try {
+ _openapi = parseOpenapi();
+ } catch {
+ _openapi = { paths: new Map(), areas: new Map() };
+ }
+ }
+ if (!_cliRegistry) {
+ try {
+ _cliRegistry = parseCliRegistry();
+ } catch {
+ _cliRegistry = { commands: new Map(), families: new Map() };
+ }
+ }
+ return { openapi: _openapi, cliRegistry: _cliRegistry };
+ }
+
+ const report: GeneratorReport = {
+ generated: [],
+ unchanged: [],
+ pruned: [],
+ orphansDetected: [],
+ errors: [],
+ };
+
+ // ── Detect orphans ──────────────────────────────────────────────────────────
+ if (prune) {
+ let dirs: string[] = [];
+ try {
+ dirs = fs
+ .readdirSync(outputBase, { withFileTypes: true })
+ .filter((e) => e.isDirectory())
+ .map((e) => e.name);
+ } catch {
+ // outputDir doesn't exist yet — no orphans
+ }
+
+ for (const dir of dirs) {
+ if (!catalogIds.has(dir)) {
+ report.orphansDetected.push(dir);
+ if (!dryRun) {
+ try {
+ fs.rmSync(path.join(outputBase, dir), { recursive: true, force: true });
+ report.pruned.push(dir);
+ } catch (err) {
+ report.errors.push({
+ id: dir,
+ error: `Failed to prune: ${err instanceof Error ? err.message : String(err)}`,
+ });
+ }
+ }
+ }
+ }
+ }
+
+ // ── Generate / compare each skill ──────────────────────────────────────────
+ const sources = getSources();
+
+ for (const skill of skillsToProcess) {
+ try {
+ const skillDir = path.join(outputBase, skill.id);
+ const skillFile = path.join(skillDir, "SKILL.md");
+
+ // Read existing content for marker preservation
+ let existingContent: string | undefined;
+ try {
+ existingContent = fs.readFileSync(skillFile, "utf-8");
+ } catch {
+ existingContent = undefined;
+ }
+
+ const { frontmatter, body } = buildSkillMarkdown(skill.id, sources, existingContent);
+ const newContent = assembleFileContent(frontmatter, body);
+
+ // Compare with existing to detect actual changes
+ if (existingContent !== undefined && existingContent === newContent) {
+ report.unchanged.push(skill.id);
+ continue;
+ }
+
+ if (dryRun) {
+ // In dry-run: classify as generated (would write) but don't touch disk
+ report.generated.push(skill.id);
+ } else {
+ // Apply: ensure directory + write file
+ fs.mkdirSync(skillDir, { recursive: true });
+ fs.writeFileSync(skillFile, newContent, "utf-8");
+ report.generated.push(skill.id);
+ }
+ } catch (err) {
+ report.errors.push({
+ id: skill.id,
+ error: err instanceof Error ? err.message : String(err),
+ });
+ }
+ }
+
+ // After writing, refresh catalog cache so subsequent calls reflect new files
+ if (!dryRun && report.generated.length > 0) {
+ refreshCatalog();
+ }
+
+ return report;
+}