@openhands/extensions 0.13.0 → 0.15.0

package/scripts/build-skills-catalog.mjs

@@ -14,6 +14,62 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const SKILLS_DIR = join(__dirname, "..", "skills");
 const OUTPUT = join(SKILLS_DIR, "index.js");
 
+const MARKETPLACES_DIR = join(__dirname, "..", "marketplaces");
+const SKILL_SOURCE_PREFIX = "./skills/";
+
+/**
+ * Categories for skill entries, consumed by the agent-canvas /skills facet rail.
+ *
+ * Distinct from the `category` on marketplace *plugin* entries, which serves Claude Code marketplace browsing and keeps its own values.
+ */
+export const SKILL_CATEGORY_IDS = [
+  "automations",
+  "environment",
+  "code-hosting",
+  "agent-authoring",
+  "code-quality",
+  "integrations",
+  "writing",
+  "design",
+  "other",
+];
+
+const FALLBACK_CATEGORY = "other";
+
+/** Build a `skill directory name -> {category, file}` map from every manifest. */
+export function buildCategoryMap(marketplacesDir) {
+  const map = new Map();
+
+  for (const filename of readdirSync(marketplacesDir).filter((f) => f.endsWith(".json")).sort()) {
+    const manifest = JSON.parse(readFileSync(join(marketplacesDir, filename), "utf-8"));
+
+    for (const entry of manifest.plugins ?? []) {
+      const source = entry.source ?? "";
+      if (!source.startsWith(SKILL_SOURCE_PREFIX)) continue;
+
+      const name = source.slice(SKILL_SOURCE_PREFIX.length);
+      const { category } = entry;
+
+      if (!SKILL_CATEGORY_IDS.includes(category)) {
+        throw new Error(
+          `${filename}: skill "${name}" has category "${category}", expected one of: ${SKILL_CATEGORY_IDS.join(", ")}`,
+        );
+      }
+
+      const existing = map.get(name);
+      if (existing && existing.category !== category) {
+        throw new Error(
+          `Conflicting categories for skill "${name}": ${existing.file} says "${existing.category}", ${filename} says "${category}"`,
+        );
+      }
+
+      map.set(name, { category, file: filename });
+    }
+  }
+
+  return map;
+}
+
 /** Minimal YAML frontmatter parser for the flat format used by SKILL.md. */
 export function parseFrontmatter(raw) {
   const result = {};
@@ -51,9 +107,15 @@ export function parseFrontmatter(raw) {
   };
 }
 
-/** Build the catalog from SKILL.md files in the given directory. */
-export function buildCatalog(skillsDir) {
+/**
+ * Build the catalog from SKILL.md files in the given directory.
+ *
+ * Pass an isolated `marketplacesDir` when building from fixtures; the default reads this repo's real manifests.
+ */
+export function buildCatalog(skillsDir, marketplacesDir = MARKETPLACES_DIR) {
   const entries = [];
+  const categories = buildCategoryMap(marketplacesDir);
+  const uncategorized = [];
 
   for (const dir of readdirSync(skillsDir).sort()) {
     const dirPath = join(skillsDir, dir);
@@ -71,16 +133,26 @@ export function buildCatalog(skillsDir) {
     const fm = parseFrontmatter(parts[1]);
     const body = parts.slice(2).join("---").trim();
 
+    const mapped = categories.get(dir);
+    if (!mapped) uncategorized.push(dir);
+
     entries.push({
       name: fm.name?.trim() || dir,
       description: fm.description,
       triggers: fm.triggers,
       content: body,
+      category: mapped?.category ?? FALLBACK_CATEGORY,
       ...(fm.license ? { license: fm.license } : {}),
       ...(fm.compatibility ? { compatibility: fm.compatibility } : {}),
     });
   }
 
+  if (uncategorized.length > 0) {
+    console.warn(
+      `Warning: no marketplace entry, category defaults to "${FALLBACK_CATEGORY}": ${uncategorized.join(", ")}`,
+    );
+  }
+
   return entries;
 }
 
@@ -90,7 +162,8 @@ if (isMain) {
   const entries = buildCatalog(SKILLS_DIR);
 
   const source = `// Auto-generated by scripts/build-skills-catalog.mjs — do not edit.
-// Source of truth: skills/*/SKILL.md
+// Source of truth: skills/*/SKILL.md and marketplaces/*.json (category)
+export const SKILL_CATEGORY_IDS = ${JSON.stringify(SKILL_CATEGORY_IDS)};
 export const SKILLS_CATALOG = ${JSON.stringify(entries, null, 2)};
 export default SKILLS_CATALOG;
 `;

package/skills/index.d.ts

@@ -1,8 +1,29 @@
+/**
+ * Categories for skill entries, consumed by the agent-canvas /skills facet rail.
+ *
+ * Sourced from the `category` field on marketplace entries whose `source` starts with `./skills/`.
+ * Distinct from the `category` on marketplace *plugin* entries, which serves Claude Code marketplace browsing.
+ */
+export type SkillCategoryId =
+  | "automations"
+  | "environment"
+  | "code-hosting"
+  | "agent-authoring"
+  | "code-quality"
+  | "integrations"
+  | "writing"
+  | "design"
+  | "other";
+
+export const SKILL_CATEGORY_IDS: readonly SkillCategoryId[];
+
 export interface SkillCatalogEntry {
   name: string;
   description: string;
   triggers: string[];
   content: string;
+  /** `"other"` when the skill has no marketplace entry. */
+  category: SkillCategoryId;
   license?: string;
   compatibility?: string;
 }