agent-skills-standard 2.1.1 → 2.1.2

package/dist/index.js

@@ -11,12 +11,32 @@ const zod = require("zod");
 const fetch$1 = require("cross-fetch");
 const child_process = require("child_process");
 class FeedbackService {
+  /**
+   * Allowed origin prefix for the feedback API to prevent SSRF.
+   * Only requests to this domain (or its subdomains) are permitted.
+   */
+  static ALLOWED_ORIGIN = "https://agent-skills-feedback.vercel.app";
   /**
    * Resolves the API URL from environment variables.
    */
   getApiUrl() {
     return "https://agent-skills-standard.onrender.com/feedback";
   }
+  /**
+   * Validates if the given URL is safe and points to the allowed feedback origin.
+   * @param url The URL to validate
+   * @returns boolean
+   */
+  isSafeUrl(url) {
+    try {
+      const parsed = new URL(url);
+      const isHttps = parsed.protocol === "https:";
+      const isVercelHostname = parsed.hostname === "agent-skills-feedback.vercel.app" || parsed.hostname.endsWith(".agent-skills-feedback.vercel.app");
+      return isHttps && isVercelHostname;
+    } catch {
+      return false;
+    }
+  }
   /**
    * Submits feedback data to the backend for automatic GitHub Issue creation.
    * Internal proxy handles GitHub tokens, keeping client-side logic tokenless.
@@ -27,6 +47,12 @@ class FeedbackService {
   async submit(data) {
     const apiUrl = this.getApiUrl();
     if (!apiUrl) return false;
+    if (!this.isSafeUrl(apiUrl)) {
+      if (process.env.DEBUG) {
+        console.warn(`[FeedbackService] Disallowed API URL origin: ${apiUrl}`);
+      }
+      return false;
+    }
     try {
       const response = await fetch(apiUrl, {
         method: "POST",
@@ -556,8 +582,8 @@ const getAgentDefinition = (id) => {
         ruleExtension: ".mdc",
         frontmatterStyle: "cursor",
         detectionFiles: [".cursor", ".cursorrules"],
-        workflowFormat: "none",
-        workflowPath: ""
+        workflowFormat: "skill",
+        workflowPath: ".cursor/skills"
       };
     case Agent.Trae:
       return {
@@ -568,8 +594,8 @@ const getAgentDefinition = (id) => {
         ruleExtension: ".mdc",
         frontmatterStyle: "cursor",
         detectionFiles: [".trae"],
-        workflowFormat: "none",
-        workflowPath: ""
+        workflowFormat: "skill",
+        workflowPath: ".trae/skills"
       };
     case Agent.Claude:
       return {
@@ -617,8 +643,8 @@ const getAgentDefinition = (id) => {
         ruleExtension: ".md",
         frontmatterStyle: "cursor",
         detectionFiles: [".codex"],
-        workflowFormat: "none",
-        workflowPath: ""
+        workflowFormat: "skill",
+        workflowPath: ".codex/skills"
       };
     case Agent.OpenCode:
       return {
@@ -629,8 +655,8 @@ const getAgentDefinition = (id) => {
         ruleExtension: ".md",
         frontmatterStyle: "cursor",
         detectionFiles: [".opencode"],
-        workflowFormat: "none",
-        workflowPath: ""
+        workflowFormat: "command",
+        workflowPath: ".opencode/commands"
       };
     case Agent.Gemini:
       return {
@@ -653,8 +679,8 @@ const getAgentDefinition = (id) => {
         ruleExtension: ".md",
         frontmatterStyle: "cursor",
         detectionFiles: [".roo"],
-        workflowFormat: "none",
-        workflowPath: ""
+        workflowFormat: "command",
+        workflowPath: ".roo/commands"
       };
     case Agent.Windsurf:
       return {
@@ -1055,7 +1081,12 @@ class DetectionService {
           dirsToScan.push(path.join(cwd, entry.name));
         }
       }
-    } catch {
+    } catch (error) {
+      if (process.env.DEBUG) {
+        console.debug(
+          `[DetectionService] Failed to read directory entries: ${error}`
+        );
+      }
     }
     const packageDepsMaps = await Promise.all(
       dirsToScan.map((dir) => this.readPackageJsonDeps(dir))
@@ -1427,7 +1458,12 @@ class GithubService {
       if (!res.ok) return null;
       const data = await res.json();
       return data.tag_name;
-    } catch {
+    } catch (error) {
+      if (process.env.DEBUG) {
+        console.warn(
+          `[GithubService] Failed to fetch latest release: ${error}`
+        );
+      }
       return null;
     }
   }
@@ -1572,7 +1608,12 @@ class RegistryService {
           ).map((f) => f.path.split("/")[2]).filter(Boolean)
         )
       );
-    } catch {
+    } catch (error) {
+      if (process.env.DEBUG) {
+        console.warn(
+          `[RegistryService] Failed to get framework skills for ${framework}: ${error}`
+        );
+      }
       return [];
     }
   }
@@ -1867,86 +1908,57 @@ applyTo: '**/*'
     }
   }
 }
-const INJECTION_PATTERNS = [
-  /ignore\s+(?:all\s+|previous\s+|prior\s+)*(?:instructions?|rules?|guidance)/gi,
-  /you\s+(?:must|should|shall|will)\s+(?:now|immediately)\b/gi,
-  /^(?:system|user|assistant)\s*:/gim,
-  /(?:^|\n)\s*-{3,}\s*(?:\n|$)/g,
-  /<(?:script|iframe|style)[^>]*\s*>[\s\S]*?<\/(?:script|iframe|style)[^>]*\s*>/gi
-];
-class IndexGeneratorService {
-  remoteMetadata;
-  /**
-   * Injects registry metadata so index generation does not require metadata.json
-   * to be present on disk. Returns `this` for chaining.
-   */
-  withMetadata(metadata) {
-    this.remoteMetadata = metadata;
-    return this;
+class IndexContentBuilder {
+  metadataReader;
+  constructor(metadataReader) {
+    this.metadataReader = metadataReader;
   }
   /**
-   * Loads foundational composite rules. Uses injected remote metadata when available;
-   * falls back to reading metadata.json from baseDir.
+   * Derives foundational composite IDs for a skill based on registry-owned naming rules.
+   * Only applies to non-common skills. Deduplicates against explicit composites.
    */
-  async loadFoundationalRules(baseDir) {
-    if (this.remoteMetadata?.foundational_composite_rules !== void 0) {
-      return this.remoteMetadata.foundational_composite_rules;
-    }
-    try {
-      const metaPath = path.join(baseDir, "metadata.json");
-      const raw = await fs.readFile(metaPath, "utf8");
-      const parsed = JSON.parse(raw);
-      return parsed.foundational_composite_rules ?? {};
-    } catch {
-      return {};
+  deriveFoundationalComposites(category, skill, explicitComposites, rules) {
+    if (category === "common") return [];
+    const derived = [];
+    for (const [foundational, patterns] of Object.entries(rules)) {
+      const matches = patterns.some((p) => skill.includes(p));
+      if (matches && !explicitComposites.includes(foundational)) {
+        derived.push(foundational);
+      }
     }
+    return derived;
   }
   /**
-   * Generates a markdown index of available skills across multiple categories.
-   * @param baseDir The base directory containing categories and skills
-   * @param allowedCategories List of categories/frameworks to include. If undefined, all found are included.
-   * @returns A formatted markdown string representing the index
+   * Formats a single skill into a list item for AGENTS.md.
    */
-  async generate(baseDir, allowedCategories) {
-    const entries = /* @__PURE__ */ new Set();
-    const foundationalRules = await this.loadFoundationalRules(baseDir);
-    if (!await fs.pathExists(baseDir)) return this.assembleIndex([]);
-    let categories = await fs.readdir(baseDir);
-    categories = categories.filter((category) => {
-      if (category.startsWith(".")) return false;
-      if (allowedCategories && !allowedCategories.includes(category) && category !== "common") {
-        return false;
-      }
-      return true;
-    });
-    categories.sort();
-    for (const category of categories) {
-      const categoryPath = path.join(baseDir, category);
-      if (!(await fs.stat(categoryPath)).isDirectory()) continue;
-      const skills = await fs.readdir(categoryPath);
-      skills.sort();
-      for (const skill of skills) {
-        const skillPath = path.join(categoryPath, skill, "SKILL.md");
-        if (!await fs.pathExists(skillPath)) continue;
-        const metadata = await this.parseSkill(skillPath);
-        if (metadata) {
-          const entry = this.formatEntry(
-            category,
-            skill,
-            metadata,
-            foundationalRules
-          );
-          entries.add(entry);
-        }
-      }
-    }
-    return this.assembleIndex(Array.from(entries));
+  formatEntry(category, skill, metadata, foundationalRules = {}) {
+    const id = `${category}/${skill}`;
+    const explicitComposites = metadata.triggers.composite || [];
+    const autoComposites = this.deriveFoundationalComposites(
+      category,
+      skill,
+      explicitComposites,
+      foundationalRules
+    );
+    const allComposites = [...explicitComposites, ...autoComposites];
+    const triggers = [
+      ...metadata.triggers.files || [],
+      ...metadata.triggers.keywords || [],
+      ...allComposites.length ? allComposites.map((c) => `+${c}`) : [],
+      ...metadata.triggers.exclude ? metadata.triggers.exclude.map((e) => `!${e}`) : []
+    ].join(", ");
+    const triggerText = triggers ? ` (triggers: \`${triggers}\`)` : "";
+    let desc = this.metadataReader.sanitizeDescription(
+      metadata.description || "",
+      id
+    );
+    desc = desc.replace(/\s*\(triggers:.*?\)\s*$/, "");
+    const prefixIcon = metadata.priority.startsWith("P0") ? "🚨 " : "";
+    const content = `${prefixIcon}${desc}${triggerText}`.trim();
+    return `- **[${id}]**: ${content}`;
   }
   /**
-   * Assembles the full index markdown including headers and Zero-Trust rules.
-   * @param entries List of formatted skill entries
-   * @param format The format of the entries ('detailed' or 'compact')
-   * @returns Complete markdown index string
+   * Assembles the full AGENTS.md markdown including headers and Zero-Trust rules.
    */
   assembleIndex(entries) {
     const header = [
@@ -1999,12 +2011,53 @@ class IndexGeneratorService {
       "> [!TIP]",
       "> **Indirect phrasing still counts.** Match keywords by intent, not just exact words.",
       '> Examples: "make it faster" → `performance`, "broken query" → `database`, "login flow" → `auth`, "clean up this file" → `refactor`.',
+      "",
+      "### List of Available Skills",
       ""
     ].join("\n");
     return `${header}
 ${entries.join("\n")}
 `;
   }
+}
+class IndexGeneratorService {
+}
+const INJECTION_PATTERNS = [
+  /ignore\s+(?:all\s+|previous\s+|prior\s+)*(?:instructions?|rules?|guidance)/gi,
+  /you\s+(?:must|should|shall|will)\s+(?:now|immediately)\b/gi,
+  /^(?:system|user|assistant)\s*:/gim,
+  /(?:^|\n)\s*-{3,}\s*(?:\n|$)/g,
+  /<(?:script|iframe|style)[^>]*\s*>[\s\S]*?<\/(?:script|iframe|style)[^>]*\s*>/gi
+];
+class MetadataReader {
+  remoteMetadata;
+  constructor(remote) {
+    this.remoteMetadata = remote;
+  }
+  /**
+   * Loads foundational composite rules. Uses injected remote metadata when available;
+   * falls back to reading metadata.json from baseDir.
+   */
+  async loadFoundationalRules(baseDir) {
+    if (this.remoteMetadata?.foundational_composite_rules !== void 0) {
+      return this.remoteMetadata.foundational_composite_rules;
+    }
+    try {
+      const metaPath = path.join(baseDir, "metadata.json");
+      if (await fs.pathExists(metaPath)) {
+        const raw = await fs.readFile(metaPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.foundational_composite_rules ?? {};
+      }
+    } catch (error) {
+      if (process.env.DEBUG) {
+        console.warn(
+          `[MetadataReader] Failed to load foundational rules: ${error}`
+        );
+      }
+    }
+    return {};
+  }
   /**
    * Loads file routing rules. Uses injected remote metadata when available;
    * falls back to reading metadata.json from baseDir.
@@ -2015,12 +2068,17 @@ ${entries.join("\n")}
     }
     try {
       const metaPath = path.join(baseDir, "metadata.json");
-      const raw = await fs.readFile(metaPath, "utf8");
-      const parsed = JSON.parse(raw);
-      return parsed.file_routing ?? {};
-    } catch {
-      return {};
+      if (await fs.pathExists(metaPath)) {
+        const raw = await fs.readFile(metaPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.file_routing ?? {};
+      }
+    } catch (error) {
+      if (process.env.DEBUG) {
+        console.warn(`[MetadataReader] Failed to load file routing: ${error}`);
+      }
     }
+    return {};
   }
   /**
    * Loads broad glob patterns and base language skill mappings. Uses injected remote
@@ -2035,40 +2093,215 @@ ${entries.join("\n")}
     }
     try {
       const metaPath = path.join(baseDir, "metadata.json");
-      const raw = await fs.readFile(metaPath, "utf8");
-      const parsed = JSON.parse(raw);
+      if (await fs.pathExists(metaPath)) {
+        const raw = await fs.readFile(metaPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+          broadGlobs: parsed.broad_globs ?? [],
+          baseSkills: parsed.base_language_skills ?? {}
+        };
+      }
+    } catch (error) {
+      if (process.env.DEBUG) {
+        console.warn(`[MetadataReader] Failed to load tier config: ${error}`);
+      }
+    }
+    return { broadGlobs: [], baseSkills: {} };
+  }
+  /**
+   * Parses a SKILL.md file to extract its metadata (frontmatter + priority).
+   */
+  async parseSkill(skillPath) {
+    try {
+      const content = await fs.readFile(skillPath, "utf8");
+      const frontmatterMatch = content.match(
+        /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/
+      );
+      if (!frontmatterMatch) return null;
+      const fm = yaml.load(frontmatterMatch[1]);
+      const body = frontmatterMatch[2];
+      const priorityMatch = body.match(/## \*\*Priority:\s*([^*]+)\*\*/);
+      const priority = priorityMatch ? priorityMatch[1].trim() : "P1";
+      const metadata = fm?.metadata || {};
+      const rawTriggers = metadata?.triggers || {};
+      const triggers = {
+        files: Array.isArray(rawTriggers.files) ? rawTriggers.files : [],
+        keywords: Array.isArray(rawTriggers.keywords) ? rawTriggers.keywords : [],
+        composite: Array.isArray(rawTriggers.composite) ? rawTriggers.composite : [],
+        exclude: Array.isArray(rawTriggers.exclude) ? rawTriggers.exclude : []
+      };
+      const hasStructured = (triggers.files?.length || 0) > 0 || (triggers.keywords?.length || 0) > 0;
+      const description = typeof fm.description === "string" ? fm.description : "";
+      if (!hasStructured && description) {
+        const descTrigs = description.match(/\(triggers:\s*`?(.*?)`?\)\s*$/);
+        if (descTrigs) {
+          const rawParts = descTrigs[1].split(",");
+          const parts = [];
+          let current = "";
+          let braceCount = 0;
+          for (let i = 0; i < rawParts.length; i++) {
+            const p = rawParts[i];
+            braceCount += (p.match(/{/g) || []).length;
+            braceCount -= (p.match(/}/g) || []).length;
+            current += (current ? "," : "") + p;
+            if (braceCount === 0) {
+              parts.push(current.trim());
+              current = "";
+            }
+          }
+          if (current) parts.push(current.trim());
+          const files = parts.filter(
+            (p) => p.includes("*") || p.includes("/") || p.includes("{") || /\.\w+$/.test(p)
+          );
+          const keywords = parts.filter(
+            (p) => !p.includes("*") && !p.includes("/") && !p.includes("{") && !/\.\w+$/.test(p)
+          );
+          if (files.length > 0) triggers.files = files;
+          if (keywords.length > 0) triggers.keywords = keywords;
+        }
+      }
       return {
-        broadGlobs: parsed.broad_globs ?? [],
-        baseSkills: parsed.base_language_skills ?? {}
+        name: typeof fm.name === "string" ? fm.name : "",
+        description,
+        priority,
+        triggers
       };
-    } catch {
-      return { broadGlobs: [], baseSkills: {} };
+    } catch (error) {
+      if (process.env.DEBUG) {
+        console.warn(
+          `[MetadataReader] Failed to parse skill at ${skillPath}: ${error}`
+        );
+      }
+      return null;
     }
   }
   /**
-   * Generates a tiered per-category _INDEX.md with two sections:
-   * - **File Match**: Skills with specific path patterns (auto-match when editing a file)
-   * - **Keyword Match**: Skills triggered by user intent (only when user mentions the concept)
-   *
-   * Broad globs (e.g., **\/*.ts) are stripped from non-base skills and those skills
-   * are moved to Keyword Match only. This prevents 30+ skills from matching a single file.
+   * Sanitizes a skill description to prevent indirect prompt injection.
    */
+  sanitizeDescription(desc, skillId = "unknown") {
+    let sanitized = desc;
+    let wasModified = false;
+    for (const pattern of INJECTION_PATTERNS) {
+      if (pattern.test(sanitized)) {
+        wasModified = true;
+        sanitized = sanitized.replace(pattern, "[REDACTED]");
+      }
+      pattern.lastIndex = 0;
+    }
+    if (wasModified) {
+      process.stderr.write(
+        `[SECURITY] Prompt injection pattern stripped from skill description: ${skillId}
+`
+      );
+    }
+    return sanitized;
+  }
+}
+class IndexGeneratorServiceImpl extends IndexGeneratorService {
+  reader;
+  builder;
+  constructor(remoteMetadata) {
+    super();
+    this.reader = new MetadataReader(remoteMetadata);
+    this.builder = new IndexContentBuilder(this.reader);
+  }
+  /** Overridable metadata injection */
+  withMetadata(metadata) {
+    this.reader = new MetadataReader(metadata);
+    this.builder = new IndexContentBuilder(this.reader);
+    return this;
+  }
+  async generate(baseDir, allowedCategories) {
+    const entries = /* @__PURE__ */ new Set();
+    const foundationalRules = await this.reader.loadFoundationalRules(baseDir);
+    if (!await fs.pathExists(baseDir)) return this.assembleIndex([]);
+    let categories = await fs.readdir(baseDir);
+    categories = categories.filter((category) => {
+      if (category.startsWith(".")) return false;
+      if (allowedCategories && !allowedCategories.includes(category) && category !== "common") {
+        return false;
+      }
+      return true;
+    });
+    categories.sort();
+    for (const category of categories) {
+      const categoryPath = path.join(baseDir, category);
+      if (!(await fs.stat(categoryPath)).isDirectory()) continue;
+      const skills = await fs.readdir(categoryPath);
+      skills.sort();
+      for (const skill of skills) {
+        const skillPath = path.join(categoryPath, skill, "SKILL.md");
+        const isRegistrySkill = await fs.pathExists(skillPath);
+        const isStandaloneSkill = !isRegistrySkill && skill.endsWith(".md") && skill !== "_INDEX.md" && !(await fs.stat(path.join(categoryPath, skill))).isDirectory();
+        const targetPath = isRegistrySkill ? skillPath : path.join(categoryPath, skill);
+        if (!isRegistrySkill && !isStandaloneSkill) continue;
+        const metadata = await this.reader.parseSkill(targetPath);
+        if (metadata) {
+          const skillId = isStandaloneSkill ? skill.replace(".md", "") : skill;
+          const entry = this.builder.formatEntry(
+            category,
+            skillId,
+            metadata,
+            foundationalRules
+          );
+          entries.add(entry);
+        }
+      }
+    }
+    return this.assembleIndex(Array.from(entries));
+  }
+  assembleIndex(entries) {
+    return this.builder.assembleIndex(entries);
+  }
+  /**
+   * Sanitizes a skill description to prevent indirect prompt injection.
+   */
+  sanitizeDescription(desc, skillId = "unknown") {
+    return this.reader.sanitizeDescription(desc, skillId);
+  }
+  /**
+   * Generates all _INDEX.md files for categories found in baseDir.
+   */
+  async generateAllCategoryIndices(baseDir, allowedCategories) {
+    if (!await fs.pathExists(baseDir)) return {};
+    let categories = await fs.readdir(baseDir);
+    categories = categories.filter((c) => {
+      if (c.startsWith(".") || c === "_INDEX.md") return false;
+      if (allowedCategories && !allowedCategories.includes(c) && c !== "common") {
+        return false;
+      }
+      return true;
+    });
+    categories.sort();
+    const result = {};
+    for (const category of categories) {
+      const categoryPath = path.join(baseDir, category);
+      if (!(await fs.stat(categoryPath)).isDirectory()) continue;
+      const index = await this.generateCategoryIndex(baseDir, category);
+      if (index) result[category] = index;
+    }
+    return result;
+  }
   async generateCategoryIndex(baseDir, category) {
     const categoryPath = path.join(baseDir, category);
     if (!await fs.pathExists(categoryPath)) return "";
-    const { broadGlobs, baseSkills } = await this.loadTierConfig(baseDir);
+    const { broadGlobs, baseSkills } = await this.reader.loadTierConfig(baseDir);
     const baseSkillForCategory = baseSkills[category];
-    const skills = await fs.readdir(categoryPath);
-    skills.sort();
+    const entries = await fs.readdir(categoryPath);
+    entries.sort();
     const fileMatchRows = [];
     const keywordMatchRows = [];
-    for (const skill of skills) {
-      if (skill.startsWith(".") || skill === "_INDEX.md") continue;
-      const skillPath = path.join(categoryPath, skill, "SKILL.md");
-      if (!await fs.pathExists(skillPath)) continue;
-      const metadata = await this.parseSkill(skillPath);
+    for (const entryName of entries) {
+      if (entryName.startsWith(".") || entryName === "_INDEX.md") continue;
+      const skillPath = path.join(categoryPath, entryName, "SKILL.md");
+      const isRegistrySkill = await fs.pathExists(skillPath);
+      const isStandaloneSkill = !isRegistrySkill && entryName.endsWith(".md") && !(await fs.stat(path.join(categoryPath, entryName))).isDirectory();
+      if (!isRegistrySkill && !isStandaloneSkill) continue;
+      const targetPath = isRegistrySkill ? skillPath : path.join(categoryPath, entryName);
+      const skillId = isStandaloneSkill ? entryName.replace(".md", "") : entryName;
+      const metadata = await this.reader.parseSkill(targetPath);
       if (!metadata) continue;
-      const isBaseSkill = skill === baseSkillForCategory;
+      const isBaseSkill = skillId === baseSkillForCategory;
       const allFiles = metadata.triggers.files || [];
       const kwTrigs = (metadata.triggers.keywords || []).join(", ") || "—";
       const prefix = metadata.priority.startsWith("P0") ? "**" : "";
@@ -2078,15 +2311,15 @@ ${entries.join("\n")}
       if (isBaseSkill || specificFiles.length > 0 && !hasBroadGlob) {
         const displayFiles = isBaseSkill ? allFiles.map((f) => `\`${f}\``).join(", ") : specificFiles.map((f) => `\`${f}\``).join(", ");
         fileMatchRows.push(
-          `| ${prefix}${skill}${suffix} | ${displayFiles || "—"} | ${kwTrigs} |`
+          `| ${prefix}${skillId}${suffix} | ${displayFiles || "—"} | ${kwTrigs} |`
         );
       } else if (specificFiles.length > 0 && hasBroadGlob) {
         const displayFiles = specificFiles.map((f) => `\`${f}\``).join(", ");
         fileMatchRows.push(
-          `| ${prefix}${skill}${suffix} | ${displayFiles} | ${kwTrigs} |`
+          `| ${prefix}${skillId}${suffix} | ${displayFiles} | ${kwTrigs} |`
         );
       } else {
-        keywordMatchRows.push(`| ${prefix}${skill}${suffix} | ${kwTrigs} |`);
+        keywordMatchRows.push(`| ${prefix}${skillId}${suffix} | ${kwTrigs} |`);
       }
     }
     if (fileMatchRows.length === 0 && keywordMatchRows.length === 0) return "";
@@ -2121,39 +2354,8 @@ ${entries.join("\n")}
     );
     return lines.join("\n");
   }
-  /**
-   * Generates all _INDEX.md files for categories found in baseDir.
-   * @returns Map of category name to generated index content
-   */
-  async generateAllCategoryIndices(baseDir, allowedCategories) {
-    if (!await fs.pathExists(baseDir)) return {};
-    let categories = await fs.readdir(baseDir);
-    categories = categories.filter((c) => {
-      if (c.startsWith(".") || c === "_INDEX.md") return false;
-      if (allowedCategories && !allowedCategories.includes(c) && c !== "common") {
-        return false;
-      }
-      return true;
-    });
-    categories.sort();
-    const result = {};
-    for (const category of categories) {
-      const categoryPath = path.join(baseDir, category);
-      if (!(await fs.stat(categoryPath)).isDirectory()) continue;
-      const index = await this.generateCategoryIndex(baseDir, category);
-      if (index) result[category] = index;
-    }
-    return result;
-  }
-  /**
-   * Assembles a router-style AGENTS.md that maps file extensions to
-   * per-category _INDEX.md files. Much smaller than the flat list.
-   * @param baseDir The base directory containing skill categories
-   * @param allowedCategories Optional filter for which categories to include
-   * @returns A compact router-table markdown string
-   */
   async assembleRouterIndex(baseDir, allowedCategories) {
-    const fileRouting = await this.loadFileRouting(baseDir);
+    const fileRouting = await this.reader.loadFileRouting(baseDir);
     let availableCategories = [];
     if (await fs.pathExists(baseDir)) {
       const dirs = await fs.readdir(baseDir);
@@ -2179,9 +2381,13 @@ ${entries.join("\n")}
       extGrouped.get(key).push(ext);
       filtered.forEach((c) => coveredCategories.add(c));
     }
+    const formatRouterPattern = (ext) => {
+      if (ext.startsWith("_")) return `\`*${ext}\``;
+      return `\`*.${ext}\``;
+    };
     for (const [catKey, exts] of extGrouped) {
       const cats = catKey.split("+");
-      const extDisplay = exts.map((e) => `\`*.${e}\``).join(", ");
+      const extDisplay = exts.map((e) => formatRouterPattern(e)).join(", ");
       const catDisplay = cats.map((c) => `\`<SKILLS>/${c}/_INDEX.md\``).join(", ");
       routerRows.push(`| ${extDisplay} | ${catDisplay} |`);
     }
@@ -2205,13 +2411,13 @@ ${entries.join("\n")}
       "",
       "## Skill Resolution Protocol",
       "",
-      "Each `_INDEX.md` has two sections — follow both:",
+      "Each `_INDEX.md` has two sections - follow both:",
       "",
-      "1. **Match file type** → find the category index in the router table below.",
-      "2. **Read the `_INDEX.md`** → it has two sections:",
+      "1. **Match file type** -> find the category index in the router table below.",
+      "2. **Read the `_INDEX.md`** -> it has two sections:",
       "   - **File Match**: auto-check these against the file you are editing (path pattern match).",
       "   - **Keyword Match**: only check if the user's request mentions these concepts.",
-      "3. **Load ALL matched `SKILL.md`** → read every matched skill before writing code. The tier model keeps matches focused.",
+      "3. **Load ALL matched `SKILL.md`** -> read every matched skill before writing code. The tier model keeps matches focused.",
       "",
       "> `<SKILLS>` = your agent's skill directory (e.g., `.claude/skills/`, `.cursor/skills/`, `.gemini/skills/`).",
       "",
@@ -2219,129 +2425,13 @@ ${entries.join("\n")}
       "| --------- | ------------------- |",
       ...routerRows,
       "",
-      '> [!TIP] **Indirect phrasing counts.** "make it faster" → performance, "broken query" → database, "login flow" → auth.',
+      "> [!NOTE] **Test/spec file precedence:** `.spec.ts`, `.test.ts` -> use the `common` row (takes precedence over the generic `*.ts` row). `.spec.tsx`, `.test.tsx` -> use the `react` row (takes precedence over the generic `*.tsx` row).",
+      "",
+      '> [!TIP] **Indirect phrasing counts.** "make it faster" -> performance, "broken query" -> database, "login flow" -> auth.',
       ""
     ].join("\n");
     return header;
   }
-  async parseSkill(skillPath) {
-    try {
-      const content = await fs.readFile(skillPath, "utf8");
-      const frontmatterMatch = content.match(
-        /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/
-      );
-      if (!frontmatterMatch) return null;
-      const fm = yaml.load(frontmatterMatch[1]);
-      const body = frontmatterMatch[2];
-      const priorityMatch = body.match(/## \*\*Priority:\s*([^*]+)\*\*/);
-      const priority = priorityMatch ? priorityMatch[1].trim() : "P1";
-      let triggers = fm.metadata?.triggers || {};
-      const hasStructured = triggers.files && triggers.files.length > 0 || triggers.keywords && triggers.keywords.length > 0;
-      if (!hasStructured && fm.description) {
-        const descTrigs = fm.description.match(/\(triggers:\s*`?(.*?)`?\)\s*$/);
-        if (descTrigs) {
-          const rawParts = descTrigs[1].split(",");
-          const parts = [];
-          let current = "";
-          let braceCount = 0;
-          for (let i = 0; i < rawParts.length; i++) {
-            const p = rawParts[i];
-            braceCount += (p.match(/{/g) || []).length;
-            braceCount -= (p.match(/}/g) || []).length;
-            current += (current ? "," : "") + p;
-            if (braceCount === 0) {
-              parts.push(current.trim());
-              current = "";
-            }
-          }
-          if (current) parts.push(current.trim());
-          const files = parts.filter(
-            (p) => p.includes("*") || p.includes("/") || p.includes("{") || /\.\w+$/.test(p)
-          );
-          const keywords = parts.filter(
-            (p) => !p.includes("*") && !p.includes("/") && !p.includes("{") && !/\.\w+$/.test(p)
-          );
-          triggers = {
-            ...triggers,
-            files: files.length > 0 ? files : triggers.files,
-            keywords: keywords.length > 0 ? keywords : triggers.keywords
-          };
-        }
-      }
-      return {
-        name: fm.name || "",
-        description: fm.description || "",
-        priority,
-        triggers
-      };
-    } catch {
-      return null;
-    }
-  }
-  /**
-   * Derives foundational composite IDs for a skill based on registry-owned naming rules.
-   * Only applies to non-common skills. Deduplicates against explicit composites.
-   */
-  deriveFoundationalComposites(category, skill, explicitComposites, rules) {
-    if (category === "common") return [];
-    const derived = [];
-    for (const [foundational, patterns] of Object.entries(rules)) {
-      const matches = patterns.some((p) => skill.includes(p));
-      if (matches && !explicitComposites.includes(foundational)) {
-        derived.push(foundational);
-      }
-    }
-    return derived;
-  }
-  /**
-   * Sanitizes a skill description to prevent indirect prompt injection.
-   * Strips known instruction-hijack patterns and replaces them with [REDACTED].
-   * Logs a stderr warning for every skill that required sanitisation.
-   * @param desc The raw description string from skill frontmatter
-   * @param skillId The skill identifier (category/skill) for log context
-   * @returns Sanitised description safe to embed in AGENTS.md
-   */
-  sanitizeDescription(desc, skillId = "unknown") {
-    let sanitized = desc;
-    let wasModified = false;
-    for (const pattern of INJECTION_PATTERNS) {
-      if (pattern.test(sanitized)) {
-        wasModified = true;
-        sanitized = sanitized.replace(pattern, "[REDACTED]");
-      }
-      pattern.lastIndex = 0;
-    }
-    if (wasModified) {
-      process.stderr.write(
-        `[SECURITY] Prompt injection pattern stripped from skill description: ${skillId}
-`
-      );
-    }
-    return sanitized;
-  }
-  formatEntry(category, skill, metadata, foundationalRules = {}) {
-    const id = `${category}/${skill}`;
-    const prefix = metadata.priority.startsWith("P0") ? "🚨 " : "";
-    const explicitComposites = metadata.triggers.composite || [];
-    const autoComposites = this.deriveFoundationalComposites(
-      category,
-      skill,
-      explicitComposites,
-      foundationalRules
-    );
-    const allComposites = [...explicitComposites, ...autoComposites];
-    const triggers = [
-      ...metadata.triggers.files || [],
-      ...metadata.triggers.keywords || [],
-      ...allComposites.length ? allComposites.map((c) => `+${c}`) : [],
-      ...metadata.triggers.exclude ? metadata.triggers.exclude.map((e) => `!${e}`) : []
-    ].join(", ");
-    const triggerText = triggers ? ` (triggers: \`${triggers}\`)` : "";
-    let desc = this.sanitizeDescription(metadata.description || "", id);
-    desc = desc.replace(/\(triggers:\s*`?(.*?)`?\)/g, "(triggers: `$1`)");
-    const content = `${prefix}${desc}`.trim();
-    return `- **[${id}]**: ${content}${triggerText}`;
-  }
 }
 class SkillSyncService {
   constructor(githubService) {
@@ -2561,7 +2651,7 @@ class WorkflowTransformer {
       case "command":
         return {
           name: `${baseName}.md`,
-          content: this.toClaudeCommand(baseName, description, body)
+          content: this.toMarkdownCommand(baseName, description, body)
         };
       case "toml":
         return {
@@ -2577,6 +2667,11 @@ class WorkflowTransformer {
           name: `${baseName}.prompt.md`,
           content: this.toCopilotPrompt(description, body)
         };
+      case "skill":
+        return {
+          name: "SKILL.md",
+          content: this.toSkillMarkdown(baseName, description, body)
+        };
     }
   }
   static parseSource(content) {
@@ -2589,12 +2684,12 @@ class WorkflowTransformer {
     };
   }
   /**
-   * Claude Code custom slash command format.
-   * Lives at .claude/commands/<name>.md
+   * Markdown-based custom slash command format.
+   * Used by Claude Code (.claude/commands/), Roo Code (.roo/commands/), and OpenCode (.opencode/commands/).
    * User invokes via /<name> [arguments]
-   * $ARGUMENTS placeholder for user input.
+   * Use $ARGUMENTS as a universal placeholder for user input instructions.
    */
-  static toClaudeCommand(name, description, body) {
+  static toMarkdownCommand(name, description, body) {
     const title = name.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
     return `# ${title}
 
@@ -2635,6 +2730,26 @@ description: "${description}"
 ---
 ${body}`;
   }
+  /**
+   * Agent Skill (SKILL.md) format.
+   * Used by Cursor, Trae, and Codex.
+   * Lives at <workflowPath>/<name>/SKILL.md
+   * User invokes via /<name> in Agent/Skill interface.
+   */
+  static toSkillMarkdown(name, description, body) {
+    const title = name.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+    return `# ${title} Skill
+
+> [!IMPORTANT]
+> ${description}
+
+## Instructions
+
+When the user asks to perform this workflow, execute the following steps:
+
+${body}
+`;
+  }
 }
 class WorkflowSyncService {
   constructor(githubService) {
@@ -2754,10 +2869,20 @@ class WorkflowSyncService {
             skillsRelative
           );
           if (!transformed) continue;
-          const targetFilePath = path.join(workflowDir, transformed.name);
+          let targetFilePath;
+          if (agentDef.workflowFormat === "skill") {
+            const workflowName = fileItem.name.replace(/\.md$/, "");
+            targetFilePath = path.join(
+              workflowDir,
+              workflowName,
+              transformed.name
+            );
+          } else {
+            targetFilePath = path.join(workflowDir, transformed.name);
+          }
           if (!this.isPathSafe(targetFilePath, workflowDir)) {
             console.log(
-              pc.red(`    ❌ Security Error: Invalid path ${transformed.name}`)
+              pc.red(`    ❌ Security Error: Invalid path ${targetFilePath}`)
             );
             continue;
           }
@@ -2892,7 +3017,7 @@ class SyncService {
       );
     }
     try {
-      const generator = new IndexGeneratorService();
+      const generator = new IndexGeneratorServiceImpl();
       const baseDir = agentDef ? path.join(process.cwd(), agentDef.path) : path.join(process.cwd(), ".cursor/skills");
       const allowedCategories = Object.keys(config.skills || {});
       const githubMatch = config.registry ? GithubService.parseGitHubUrl(config.registry) : null;
@@ -3082,7 +3207,7 @@ class SyncCommand {
     }
   }
 }
-const version = "2.1.1";
+const version = "2.1.2";
 const pkg = {
   version
 };
@@ -3209,24 +3334,36 @@ class GitService {
    */
   getChangedFiles(rootDir) {
     try {
-      let gitCommand;
       if (process.env.GITHUB_BASE_REF) {
+        const baseRef = process.env.GITHUB_BASE_REF;
+        if (!/^[\w./:-]+$/.test(baseRef)) {
+          if (process.env.DEBUG) {
+            console.warn(
+              "GITHUB_BASE_REF contains unsafe characters; skipping CI diff."
+            );
+          }
+          return [];
+        }
         try {
-          child_process.execSync(
-            `git fetch origin ${process.env.GITHUB_BASE_REF} --depth=1`,
-            {
-              cwd: rootDir,
-              stdio: "ignore"
-            }
-          );
+          child_process.execFileSync("git", ["fetch", "origin", baseRef, "--depth=1"], {
+            cwd: rootDir,
+            stdio: "ignore"
+          });
         } catch {
         }
-        gitCommand = `git diff --name-only origin/${process.env.GITHUB_BASE_REF}...HEAD`;
+        const output = child_process.execFileSync(
+          "git",
+          ["diff", "--name-only", `origin/${baseRef}...HEAD`],
+          { cwd: rootDir, encoding: "utf8" }
+        );
+        return output.split("\n").map((f) => f.trim()).filter((f) => f !== "" && fs.existsSync(path.join(rootDir, f)));
       } else {
-        gitCommand = "git diff --name-only HEAD";
+        const output = child_process.execSync("git diff --name-only HEAD", {
+          cwd: rootDir,
+          encoding: "utf8"
+        });
+        return output.split("\n").map((f) => f.trim()).filter((f) => f !== "" && fs.existsSync(path.join(rootDir, f)));
       }
-      const output = child_process.execSync(gitCommand, { cwd: rootDir, encoding: "utf8" });
-      return output.split("\n").map((f) => f.trim()).filter((f) => f !== "" && fs.existsSync(path.join(rootDir, f)));
     } catch (error) {
       if (process.env.DEBUG) {
         console.warn("Git failure while getting changed files:", error);
@@ -3600,7 +3737,7 @@ dotenv.config();
 const program = new commander.Command();
 program.name("agent-skills-standard").description(
   "A CLI to manage and sync AI agent skills for Cursor, Claude, Copilot, Windsurf, and more."
-).version("2.1.1");
+).version("2.1.2");
 program.command("init").description("Initialize a .skillsrc configuration file interactively").action(async () => {
   const init = new InitCommand();
   await init.run();