@openhands/extensions 0.2.0 → 0.3.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.2.0"
+  ".": "0.3.0"
 }

package/index.d.ts

@@ -15,3 +15,5 @@ export {
 } from "./integrations/index.js";
 export { AUTOMATION_CATALOG } from "./automations/index.js";
 export type { RecommendedAutomation } from "./automations/index.js";
+export { SKILLS_CATALOG } from "./skills/index.js";
+export type { SkillCatalogEntry } from "./skills/index.js";

package/index.js

@@ -1,2 +1,3 @@
 export { INTEGRATION_CATALOG } from "./integrations/index.js";
 export { AUTOMATION_CATALOG } from "./automations/index.js";
+export { SKILLS_CATALOG } from "./skills/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,9 @@
     "type": "git",
     "url": "https://github.com/OpenHands/extensions"
   },
+  "scripts": {
+    "build:skills": "node scripts/build-skills-catalog.mjs"
+  },
   "engines": {
     "node": ">=18.20.0"
   },
@@ -42,6 +45,11 @@
       "default": "./integrations/logos.js"
     },
     "./integrations/catalog/*.json": "./integrations/catalog/*.json",
+    "./skills": {
+      "types": "./skills/index.d.ts",
+      "import": "./skills/index.js",
+      "default": "./skills/index.js"
+    },
     "./skills/*": "./skills/*",
     "./plugins/*": "./plugins/*",
     "./marketplaces/*.json": "./marketplaces/*.json",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "extensions"
-version = "0.2.0"
+version = "0.3.0"
 description = "OpenHands extensions, plugins, and skills"
 requires-python = ">=3.12"
 

package/scripts/build-skills-catalog.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Generates skills/index.js from the SKILL.md source files.
+ *
+ * Run manually or via `npm run build:skills` before publishing.
+ * The generated file is checked into git so consumers get a normal
+ * JS module import — no build-time filesystem reads needed.
+ */
+import { readdirSync, readFileSync, writeFileSync, statSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = join(__dirname, "..", "skills");
+const OUTPUT = join(SKILLS_DIR, "index.js");
+
+/** Minimal YAML frontmatter parser for the flat format used by SKILL.md. */
+export function parseFrontmatter(raw) {
+  const result = {};
+  let currentKey = null;
+
+  for (const line of raw.split("\n")) {
+    // List items
+    if (/^\s*-\s/.test(line)) {
+      if (currentKey) {
+        if (!Array.isArray(result[currentKey])) result[currentKey] = [];
+        result[currentKey].push(line.replace(/^\s*-\s*/, ""));
+      }
+      continue;
+    }
+    // Key: value (allow hyphens in key names, e.g. event-key)
+    const match = line.match(/^([\w-]+):\s*(.*)/);
+    if (match) {
+      currentKey = match[1];
+      const value = match[2].trim();
+      result[currentKey] = value && value !== ">" && value !== ">-" && value !== "|" ? value : "";
+      continue;
+    }
+    // Continuation line
+    if (currentKey && typeof result[currentKey] === "string" && line.trim()) {
+      result[currentKey] = (result[currentKey] + " " + line.trim()).trim();
+    }
+  }
+
+  return {
+    name: result.name ?? "",
+    description: result.description ?? "",
+    triggers: Array.isArray(result.triggers) ? result.triggers : [],
+    ...(result.license ? { license: result.license } : {}),
+    ...(result.compatibility ? { compatibility: result.compatibility } : {}),
+  };
+}
+
+/** Build the catalog from SKILL.md files in the given directory. */
+export function buildCatalog(skillsDir) {
+  const entries = [];
+
+  for (const dir of readdirSync(skillsDir).sort()) {
+    const dirPath = join(skillsDir, dir);
+    if (!statSync(dirPath).isDirectory()) continue;
+    const skillMd = join(dirPath, "SKILL.md");
+    if (!existsSync(skillMd)) continue;
+
+    const raw = readFileSync(skillMd, "utf-8");
+    const parts = raw.split("---");
+    if (parts.length < 3) {
+      console.warn(`Warning: ${skillMd} missing frontmatter sections, skipping`);
+      continue;
+    }
+
+    const fm = parseFrontmatter(parts[1]);
+    const body = parts.slice(2).join("---").trim();
+
+    entries.push({
+      name: fm.name?.trim() || dir,
+      description: fm.description,
+      triggers: fm.triggers,
+      content: body,
+      ...(fm.license ? { license: fm.license } : {}),
+      ...(fm.compatibility ? { compatibility: fm.compatibility } : {}),
+    });
+  }
+
+  return entries;
+}
+
+// Run codegen when executed directly (not when imported as a module).
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+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
+export const SKILLS_CATALOG = ${JSON.stringify(entries, null, 2)};
+export default SKILLS_CATALOG;
+`;
+
+  writeFileSync(OUTPUT, source);
+  console.log(`Generated ${OUTPUT} with ${entries.length} skills`);
+}

package/skills/github-pr-review/SKILL.md

@@ -76,7 +76,7 @@ For comments spanning multiple lines, add `start_line` to specify the range:
 }
 ```
 
-**Important**: The suggestion must have the same number of lines as the range (e.g., lines 10-12 = 3 lines).
+**`start_line`/`line` define the range that will be REPLACED.** The suggestion block may have any number of lines — it does **not** have to match the range size. See the next section for the exact semantics; getting this wrong is how suggestions silently delete or duplicate code.
 
 ## Priority Labels
 
@@ -114,6 +114,44 @@ Use suggestions for: renaming, typos, small refactors (1-5 lines), type hints, d
 
 Avoid for: large refactors, architectural changes, ambiguous improvements.
 
+### How Suggestions Actually Work (READ THIS BEFORE WRITING ONE)
+
+A suggestion block **replaces** the targeted range with its contents. The replaced range is:
+
+- `line` only → the single line `line` (replaces 1 line)
+- `start_line` + `line` → the inclusive range `start_line..line` (replaces `line - start_line + 1` lines)
+
+The suggestion content can be **any number of lines** — 0 (deletion), 1, or many. It does not have to match the range size. Whatever is between the ` ```suggestion ` and closing ` ``` ` fences becomes the new content of those lines.
+
+Writing the wrong combination of `start_line`/`line` and suggestion body is what causes accepted suggestions to **duplicate** or **delete** code. Use the table below as your contract:
+
+| Intent | `start_line` | `line` | Suggestion body must contain |
+|--------|--------------|--------|-------------------------------|
+| Change line N | omit | N | the new content for line N |
+| Change lines N..M | N | M | the new content for the whole block |
+| **Add** a line **after** line N (keep line N) | omit | N | line N's exact current text, then the new line(s) |
+| **Add** a line **before** line N (keep line N) | omit | N | the new line(s), then line N's exact current text |
+| **Insert** lines inside range N..M (keep N..M) | N | M | every original line in N..M plus the new lines, in the final desired order |
+| **Delete** line N | omit | N | empty body (just an empty ` ```suggestion ``` ` block) |
+| **Delete** lines N..M | N | M | empty body |
+
+### Common Mistakes That Break Code
+
+1. **Duplicated lines.** You copy a neighboring line (N-1 or N+1) into the suggestion body as context — that line is still present in the file outside the replaced range, so accepting the suggestion inserts a second copy of it. Fix: only include lines that fall within the targeted range, plus any genuinely new content.
+2. **Disappearing lines.** You target `start_line=10, line=12` to comment on a 3-line block, but your suggestion body only contains 1 line because you "only want to change line 11". Accepting that suggestion deletes lines 10 and 12. Fix: either narrow the range to just line 11, or include lines 10 and 12 verbatim in the body.
+3. **Description does not match the suggestion.** The prose says "rename this variable" but the suggestion replaces an entire function. Or the prose says "add a None check" but the suggestion only contains the check (deleting the original code). Fix: after writing the suggestion, re-read the prose and confirm the resulting file would match it line-for-line.
+
+### Mandatory Verification Before Posting
+
+For every comment that contains a ` ```suggestion ``` ` block, do this check before adding it to the review JSON:
+
+1. Read the actual file lines that will be replaced: `sed -n '<start_line>,<line>p' <path>` (or `sed -n '<line>p' <path>` for a single-line target).
+2. Mentally apply the suggestion: drop those lines, splice in the suggestion body, and look at the result in context.
+3. Confirm the resulting code matches **exactly** what your prose description promises — no extra duplicated line above/below, no original line accidentally dropped, no off-by-one.
+4. If the change cannot be expressed cleanly as a contiguous replacement (e.g., it touches non-adjacent lines, or it depends on edits elsewhere in the file), do **not** use a suggestion block — describe the change in prose instead.
+
+If you are not 100% sure the suggestion will produce the exact code you described, drop the ` ```suggestion ``` ` block and leave a regular inline comment. A correct prose comment is always better than a one-click suggestion that silently corrupts the file.
+
 ## Finding Line Numbers
 
 ```bash
@@ -143,6 +181,6 @@ curl -X POST \
 3. Post **ONE** review using `gh api --input /tmp/review.json`
 4. Use priority labels (🔴🟠🟡) on every comment
 5. Do NOT post comments for code that is acceptable — only comment when action is needed
-6. Use suggestion syntax for concrete code changes
+6. Use suggestion syntax for concrete code changes, but only after verifying the resulting code matches your description (see "How Suggestions Actually Work")
 7. Keep the review body brief (details go in inline comments)
 8. If no issues: post a short approval message with no inline comments

package/skills/index.d.ts

@@ -0,0 +1,11 @@
+export interface SkillCatalogEntry {
+  name: string;
+  description: string;
+  triggers: string[];
+  content: string;
+  license?: string;
+  compatibility?: string;
+}
+
+export const SKILLS_CATALOG: SkillCatalogEntry[];
+export default SKILLS_CATALOG;