@openhands/extensions 0.1.0 → 0.2.0

package/.agents/skills/custom-codereview-guide.md

@@ -0,0 +1,25 @@
+---
+name: custom-codereview-guide
+description: Repository-specific code review guidelines for OpenHands/extensions
+triggers:
+- /codereview
+---
+
+# Extensions Repo — Code Review Guidelines
+
+## SDK Documentation Placement
+
+If a PR adds or modifies OpenHands SDK-specific documentation (API guides, SDK usage examples, SDK feature descriptions), flag it:
+
+- The canonical source of truth for SDK documentation is <https://docs.openhands.dev/sdk> and its `llms.txt` index.
+- The `skills/openhands-sdk/SKILL.md` in this repo is a thin pointer to the docs site. It should NOT contain duplicated SDK content.
+- **Push back**: ask the submitter to contribute SDK documentation changes to [OpenHands/docs](https://github.com/OpenHands/docs) instead.
+
+## Pre-release Integration Catalog Changes
+
+The `@openhands/extensions/mcps` catalog was experimental and pre-release. If a
+PR intentionally replaces it with the broader `integrations` catalog and updates
+known downstream consumers in the same coordinated stack, do not require
+backward-compatible `mcps` aliases or a deprecation window. Require migration
+documentation for consumers, but accept a clean breaking change for this
+pre-release surface.

package/.github/pull_request_template.md

@@ -0,0 +1,38 @@
+<!-- Keep this PR as draft until it is ready for review. -->
+
+<!-- AI/LLM agents: be concise and specific. Do not check the box below. -->
+
+- [ ] A human has tested these changes.
+
+---
+
+## Why
+
+<!-- Describe problem, motivation, etc.-->
+
+## Summary
+
+<!-- 1-3 bullets describing what changed. -->
+-
+
+## Issue Number
+<!-- Required if there is a relevant issue to this PR. -->
+
+## How to Test
+
+<!--
+Required. Share the steps for the reviewer to be able to test your PR. e.g. You can test by running `npm install` then `npm build dev`.
+
+If you could not test this, say why.
+-->
+
+## Video/Screenshots
+
+<!--
+Provide a video or screenshots of testing your PR. e.g. you added a new feature to the gui, show us the video of you testing it successfully.
+
+-->
+
+## Notes
+
+<!-- Optional: migrations, config changes, rollout concerns, follow-ups, or anything reviewers should know. -->

package/.github/release.yml

@@ -0,0 +1,14 @@
+changelog:
+  categories:
+    - title: Features
+      labels: ["type: feat"]
+    - title: Bug Fixes
+      labels: ["type: fix"]
+    - title: Performance
+      labels: ["type: perf"]
+    - title: Documentation
+      labels: ["type: docs"]
+    - title: Maintenance
+      labels: ["type: chore", "type: build", "type: ci", "type: refactor", "type: style", "type: test", "type: revert"]
+    - title: Other Changes
+      labels: ["*"]

package/.github/workflows/check-extensions.yml

@@ -0,0 +1,72 @@
+name: Check Extensions
+
+on:
+  pull_request:
+    branches: ["*"]
+  push:
+    branches: ["main", "master"]
+
+jobs:
+  validate-claude-code:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Validate all plugins with Claude Code
+        run: |
+          failed=0
+          for plugin_dir in plugins/*/; do
+            if [ -d "${plugin_dir}.plugin" ]; then
+              echo "Validating ${plugin_dir}..."
+              if ! claude plugin validate "${plugin_dir}"; then
+                echo "❌ Validation failed for ${plugin_dir}"
+                failed=1
+              else
+                echo "✅ ${plugin_dir} is valid"
+              fi
+            fi
+          done
+          if [ "$failed" -ne 0 ]; then
+            echo "::error::One or more plugins failed Claude Code validation"
+            exit 1
+          fi
+
+  sync-extensions:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Check extensions are in sync
+        run: python scripts/sync_extensions.py --check
+
+  sync-sdk-skill:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Check SDK skill is up to date
+        run: python scripts/sync_openhands_sdk_skill.py --check

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,89 @@
+name: Publish to npm
+
+# Publishes @openhands/extensions to npm via OIDC trusted publishing (no token).
+# Fires when release-please pushes a version tag (v*) cut from main; the manual
+# dispatch path re-publishes a specific tag. Trusted publishing must be
+# configured for this package on npmjs.com (this repo + this workflow file).
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to publish (e.g. v0.1.0)'
+        required: true
+        type: string
+
+concurrency:
+  group: npm-publish-${{ inputs.tag || github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      # Trusted publishing requires Node 22.14.0+ and npm 11.5.1+
+      # See: https://docs.npmjs.com/trusted-publishers/
+      - name: Set up Node.js for npm trusted publishing
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          registry-url: https://registry.npmjs.org
+
+      - name: Verify npm version supports trusted publishing
+        run: |
+          echo "Node version: $(node --version)"
+          echo "npm version: $(npm --version)"
+          NPM_VERSION=$(npm --version)
+          NPM_MAJOR=$(echo $NPM_VERSION | cut -d. -f1)
+          NPM_MINOR=$(echo $NPM_VERSION | cut -d. -f2)
+          if [ "$NPM_MAJOR" -lt 11 ] || ([ "$NPM_MAJOR" -eq 11 ] && [ "$NPM_MINOR" -lt 5 ]); then
+            echo "Error: npm 11.5.1+ required for trusted publishing, got $NPM_VERSION"
+            exit 1
+          fi
+          echo "✓ npm $NPM_VERSION meets trusted publishing requirements"
+
+      # No install/test/build steps: @openhands/extensions ships source directly
+      # (plain ESM + hand-written .d.ts + JSON catalogs) with only peerDependencies,
+      # and has no build script, test suite, or lockfile.
+
+      - name: Verify package contents
+        run: npm pack --dry-run
+
+      - name: Validate package version matches release tag
+        env:
+          # Pass inputs.tag via env var to prevent script injection from
+          # GitHub Actions expression interpolation inside run blocks.
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          # Resolve tag: prefer workflow_dispatch input, fall back to push-event GITHUB_REF
+          if [ -n "$INPUT_TAG" ]; then
+            RAW_TAG="$INPUT_TAG"
+          else
+            RAW_TAG="${GITHUB_REF#refs/tags/}"
+          fi
+          TAG_VERSION="${RAW_TAG#v}"
+          echo "Package version: $PACKAGE_VERSION"
+          echo "Release tag version: $TAG_VERSION"
+          if [ "$PACKAGE_VERSION" != "$TAG_VERSION" ]; then
+            echo "Error: package.json version ($PACKAGE_VERSION) doesn't match release tag ($TAG_VERSION)"
+            exit 1
+          fi
+          echo "✓ Version $PACKAGE_VERSION matches release tag"
+
+      - name: Publish to npm with provenance
+        run: npm publish --access public --provenance

package/.github/workflows/pr.yml

@@ -0,0 +1,30 @@
+name: pr
+
+# Caller workflow for the shared PR-title lint/label in OpenHands/release-actions.
+#
+# Trigger is pull_request_target (NOT pull_request) so the lint/label also runs
+# on PRs from forks — e.g. external contributors who aren't org members. On a
+# fork-originated `pull_request`, GITHUB_TOKEN is read-only, so the label step
+# (which needs pull-requests: write) would fail; pull_request_target runs in the
+# base repo's context with a writable token.
+#
+# pull_request_target is safe here — and only stays safe — because of two
+# invariants enforced by the reusable workflow:
+#   1. It NEVER checks out or executes any code from the PR. It only reads the
+#      PR title from the event payload, so fork code never runs with the base
+#      repo's token/secrets. Do not add a checkout step.
+#   2. This caller does NOT pass `secrets: inherit`, so the release App's
+#      credentials are not in scope for the title workflow — it runs on the
+#      default GITHUB_TOKEN alone. Do not add `secrets: inherit`.
+on:
+  pull_request_target:
+    # synchronize is needed alongside the title events: required status checks
+    # attach to a head SHA, and release-please force-pushes new commits to its
+    # release PR, so the lint must re-run on each update to stay green.
+    types: [opened, edited, reopened, synchronize]
+
+jobs:
+  pr-title:
+    permissions:
+      pull-requests: write
+    uses: OpenHands/release-actions/.github/workflows/pr-title.yml@main

package/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: release
+
+# Caller workflow for the shared release automation in OpenHands/release-actions.
+# This file owns the trigger; the reusable workflow owns the logic.
+on:
+  push:
+    branches:
+      - main
+      # Maintenance/freeze branches (e.g. release/0.2). The reusable workflow
+      # scopes the release to whichever branch triggered this run.
+      - 'release/**'
+
+jobs:
+  release-please:
+    # The caller must grant the permissions the reusable workflow needs; the
+    # effective token is the intersection of the two.
+    permissions:
+      contents: write
+      pull-requests: write
+    # Passes the org-level RELEASE_APP_ID / RELEASE_APP_PRIVATE_KEY through so the
+    # reusable workflow can mint the GitHub App token. These are org secrets —
+    # nothing to create per-repo.
+    secrets: inherit
+    uses: OpenHands/release-actions/.github/workflows/release-please.yml@main

package/.github/workflows/tests.yml

@@ -0,0 +1,25 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: ["*"]
+  push:
+    branches: ["main", "master"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Run tests
+        run: uv run --group test pytest tests/
+        env:
+          PYTHONPATH: ${{ github.workspace }}

package/.github/workflows/vulnerability-scan.yml

@@ -0,0 +1,87 @@
+# Vulnerability Scan and Remediation Workflow
+#
+# This is a thin wrapper that uses the OpenHands vulnerability-remediation action.
+# It auto-updates when the action in OpenHands/extensions is updated.
+#
+# INSTALLATION:
+#   curl -o .github/workflows/vulnerability-scan.yml \
+#     https://raw.githubusercontent.com/OpenHands/extensions/main/plugins/vulnerability-remediation/workflows/vulnerability-scan.yml
+#
+# REQUIRED SECRETS:
+#   - LLM_API_KEY: API key for your LLM provider (OpenAI, Anthropic, etc.)
+#
+# OPTIONAL SECRETS:
+#   - PAT_TOKEN: GitHub PAT for creating PRs (uses GITHUB_TOKEN if not set)
+#
+# The action will:
+#   1. Run a Trivy security scan
+#   2. Skip agent if no vulnerabilities found (saves costs)
+#   3. Create PRs for fixable vulnerabilities
+
+name: Vulnerability Scan and Remediation
+
+on:
+    # Run weekly on Monday at 9am UTC
+    schedule:
+        - cron: '0 9 * * 1'
+
+    # Allow manual trigger
+    workflow_dispatch:
+        inputs:
+            severity_threshold:
+                description: 'Minimum severity to remediate'
+                required: false
+                default: 'HIGH'
+                type: choice
+                options:
+                    - CRITICAL
+                    - HIGH
+                    - MEDIUM
+                    - LOW
+            max_vulnerabilities:
+                description: 'Maximum vulnerabilities to fix (0 = unlimited)'
+                required: false
+                default: '5'
+                type: string
+            llm_model:
+                description: 'LLM model to use for remediation'
+                required: false
+                default: 'anthropic/claude-sonnet-4-5-20250929'
+                type: string
+            llm_base_url:
+                description: 'Custom LLM base URL (optional)'
+                required: false
+                default: ''
+                type: string
+
+permissions:
+    contents: write
+    pull-requests: write
+    security-events: read
+
+jobs:
+    scan-and-remediate:
+        runs-on: ubuntu-latest
+        timeout-minutes: 60
+
+        steps:
+            # Uses @main to auto-update when the action is improved
+            - name: Run Vulnerability Remediation
+              id: remediate
+              uses: OpenHands/extensions/plugins/vulnerability-remediation@main
+              with:
+                  severity-threshold: ${{ inputs.severity_threshold || 'HIGH' }}
+                  max-vulnerabilities: ${{ inputs.max_vulnerabilities || '5' }}
+                  llm-model: ${{ inputs.llm_model || 'anthropic/claude-sonnet-4-5-20250929' }}
+                  llm-base-url: ${{ inputs.llm_base_url || '' }}
+                  llm-api-key: ${{ secrets.LLM_API_KEY }}
+                  github-token: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC || secrets.GITHUB_TOKEN }}
+
+            - name: Summary
+              run: |
+                  echo "### Vulnerability Scan Results" >> $GITHUB_STEP_SUMMARY
+                  if [ "${{ steps.remediate.outputs.scan-only }}" == "true" ]; then
+                    echo "✅ No vulnerabilities found that need remediation." >> $GITHUB_STEP_SUMMARY
+                  else
+                    echo "🔍 Found ${{ steps.remediate.outputs.vulnerabilities-found }} vulnerabilities to remediate." >> $GITHUB_STEP_SUMMARY
+                  fi

package/.release-please-manifest.json

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

package/AGENTS.md

@@ -0,0 +1,132 @@
+# OpenHands Extensions — Agent Notes
+
+This repository (`OpenHands/extensions`) is the **public extensions registry** for OpenHands.
+It contains **shareable skills and plugins** that can be loaded by OpenHands (CLI/GUI/Cloud) and by client code using the **Software Agent SDK**.
+
+## What this repo contains
+
+- `skills/` — a catalog of skills, **one directory per skill**.
+  - `skills/<skill-name>/SKILL.md` — the skill definition (AgentSkills-style progressive disclosure)
+  - `skills/<skill-name>/README.md` — optional extra docs/examples for humans
+
+- `plugins/` — a catalog of plugins with executable code components.
+  - `plugins/<plugin-name>/SKILL.md` — the plugin definition
+  - `plugins/<plugin-name>/hooks/` — lifecycle hooks (optional)
+  - `plugins/<plugin-name>/scripts/` — utility scripts (optional)
+
+There is no application code here; the primary artifacts are Markdown skill definitions and plugin configurations, which can contain `scripts/`, `hooks/` sub-directories.
+
+## How client code uses this repo
+
+### OpenHands Applications
+
+OpenHands can load skills from a project directory (repo-level) and from user-level locations.
+This repository is the **global/public** registry referenced by the docs.
+
+### Skill loading models to know
+
+OpenHands supports two complementary mechanisms:
+
+1. **Always-on context (repository rules)**
+   - Loaded at conversation start.
+   - Prefer a root `AGENTS.md` (and optionally model-specific variants like `CLAUDE.md` / `GEMINI.md`).
+
+2. **AgentSkills (progressive disclosure), with an OpenHands extension for keyword triggers**
+   - Each skill lives in its own directory with a `SKILL.md` entry point.
+   - The agent is shown a catalog (name/description/location) and decides when to open/read the full content.
+   - **OpenHands extension**: the `SKILL.md` may include optional `triggers:` frontmatter to enable keyword-based activation.
+
+This registry primarily provides (2). Client repositories typically add (1) for repo-specific, always-on instructions.
+
+### Software Agent SDK
+
+SDK consumers typically load skills either:
+
+- as **always-loaded context** (e.g., `AGENTS.md`), and/or
+- as **trigger-loaded keyword skills**, and/or
+- as **progressive-disclosure AgentSkills** by discovering `SKILL.md` files under a directory.
+
+See: https://docs.openhands.dev/sdk/guides/skill
+
+## AgentSkills / Skill authoring rules (follow these)
+
+OpenHands uses an **extended AgentSkills standard**:
+
+- **Compatible with the AgentSkills specification** (https://agentskills.io/specification)
+- **Extended with optional `triggers:` frontmatter** for keyword-based activation
+
+When editing or adding skills in this repo, follow these rules (and add new skills to `marketplaces/openhands-extensions.json`):
+
+1. **One skill per directory**
+   - Create `skills/<skill-name>/SKILL.md`.
+   - Keep the directory name stable; it is used as the skill identifier/location.
+
+2. **SKILL.md should be progressive disclosure**
+   - Put a concise summary/description first.
+   - Include only the information needed for an agent to decide whether to open/read the skill.
+   - If the skill needs large references, keep them in the same directory (e.g., `references/`) and point to them.
+
+3. **Be specific and operational**
+   - Prefer checklists, steps, and concrete examples.
+   - Avoid vague guidance like “be careful” without actionable criteria.
+
+4. **Avoid repo-local assumptions**
+   - Skills here are **public and reusable**.
+   - Don’t reference private paths, secrets, or company-specific URLs.
+
+5. **Do not include secrets or sensitive data**
+   - Never commit API keys, tokens, credentials, private endpoints, or internal customer data.
+
+6. **Prefer minimal, composable skills**
+   - Keep a skill focused on a single domain/task.
+   - If it grows large, split it into multiple skills.
+
+7. **Compatibility notes**
+   - The legacy `.openhands/microagents/` location may still exist in user repos, but this registry uses the current skills layout.
+
+## Repository conventions
+
+- **Punctuation style**: Use plain hyphens (`-`) instead of em dashes (`—` / `\u2014`) in skill descriptions, SKILL.md content, and marketplace JSON entries.
+- Keep formatting consistent across skills.
+- If you change a skill’s behavior or scope, update its `README.md` (if present) accordingly.
+- If you change top-level documentation, ensure links still resolve.
+- `integrations/catalog/*.json` and `integrations/index.js` are the source of truth consumed by `@openhands/extensions`; agent-canvas and integrations-hub import this package directly, so integration marketplace fixes belong here rather than in app-local constants. When upstream MCP projects move repos, verify both `docsUrl` and the connection option (`transport`, `command`/`args`, or URL), not just links.
+- For Python test runs, prefer `uv sync --group test` followed by `uv run pytest -q`; the full suite depends on `openhands-sdk`, which is not available in the base environment.
+- Agent-driven plugins (for example `plugins/pr-review` and `plugins/release-notes`) use `uv run --with openhands-sdk --with openhands-tools ...` and require an `LLM_API_KEY` in addition to `GITHUB_TOKEN`.
+- For OpenHands Cloud API guidance, automations, and CLI integration, use `plugins/openhands`. It is the canonical unified OpenHands plugin covering the V1 Cloud API, Automations API, and CLI. The individual skills (`skills/openhands-api`, `skills/openhands-automation`) are also available standalone.
+- When reviewing or editing `skills/openhands-sdk`, validate copy-paste imports against the released packages with `uv run --with openhands-tools --with openhands-workspace --with openhands-agent-server python ...`. In the current released workspace package, the exported remote workspace classes are `APIRemoteWorkspace` / `OpenHandsCloudWorkspace`; `RemoteAPIWorkspace` is not available.
+- For agent-driven plugin scripts, prefer `from openhands.sdk.plugin import PluginSource` and pass `plugins=[PluginSource(source=...)]` into `Conversation`. In the current released SDK (`openhands-sdk` 1.18.x), `Plugin` is not exported from `openhands.sdk.plugin`, so direct `Plugin.load(...)` imports can break CI.
+- `plugins/qa-changes/action.yml` now has a preflight guard for fork PRs in `pull_request` context: if the PR comes from a fork and `LLM_API_KEY` is unavailable (normal for forks), the action exits successfully with a clear skip notice instead of failing.
+- `skills/bitbucket` should not tell agents to rewrite remotes proactively. In OpenHands, `BITBUCKET_TOKEN` is commonly kept in unencoded `user:token` form for API calls like `curl --user "$BITBUCKET_TOKEN" ...`; only split and URL-encode it when constructing a non-interactive HTTPS Git remote URL.
+
+- `plugins/release-notes` now has a standalone validator at `plugins/release-notes/scripts/validate_release_notes.py`; it rebuilds the deterministic tag-range context, fails if a change bullet omits explicit PR/commit refs or matching author handles, and enforces full PR/author coverage by appending a compact `### 🔎 Small Fixes/Internal Changes` appendix grouped by author when the agent omits lower-signal items. New contributor detection in `generate_release_notes.py` should use merged PR history for human authors (excluding bots) rather than commit-author lookup.
+
+
+## CI / validation gotchas
+
+- The test suite expects **every directory under `skills/`** to be listed in a marketplace. If you add a new skill (or rebase onto a main branch that added skills), update the appropriate marketplace file or CI will fail with `Skills missing from marketplace: [...]`.
+- `scripts/sync_extensions.py` keeps generated artifacts in sync: Claude Code command files, README catalog section, coverage checks, and vendor symlinks. Run `python scripts/sync_extensions.py --check` (or just push — CI runs it) to verify everything is consistent. Run without `--check` to auto-fix. The "Quick Start" section in `README.md` (OpenHands SDK, Claude Code, and Codex setup instructions) is **manually maintained** above the auto-generated catalog markers and is intentionally not generated by the sync script.
+- The sync script uses PyYAML to parse SKILL.md frontmatter. If you add a skill with a slash trigger (e.g., `triggers: ["/mycommand"]`), the script auto-generates `commands/mycommand.md`. **Note:** Slash triggers in SKILL.md frontmatter are deprecated — prefer adding a `commands/command-name.md` file to the plugin's `commands/` directory instead. Keyword triggers (non-slash) remain the recommended way to activate skills by topic.
+
+## OpenHands SDK documentation policy
+
+- **Do NOT add SDK-specific or SDK-related documentation to this repo.** The canonical source of truth for SDK documentation is the [OpenHands docs site](https://docs.openhands.dev/sdk) and its structured index at <https://docs.openhands.dev/llms.txt>.
+- The `skills/openhands-sdk/SKILL.md` is **auto-generated** by `scripts/sync_openhands_sdk_skill.py`. It pulls class names, guides, examples, and the hello-world snippet directly from the docs site and the SDK repo. **Do not edit SKILL.md by hand** - run the script to regenerate it.
+- CI runs `python scripts/sync_openhands_sdk_skill.py --check` on every PR. If the skill is out of date, regenerate it with `python scripts/sync_openhands_sdk_skill.py`.
+- If a PR adds or modifies SDK-specific documentation in this repo, **push back**: ask the submitter to contribute those changes to [OpenHands/docs](https://github.com/OpenHands/docs) instead.
+
+## PR review plugin notes
+
+- The `code-review` and `codereview-roasted` skills have been merged into a single `code-review` skill. The `/codereview-roasted` trigger is kept as an alias for backward compatibility. The `review-style` action input is deprecated and ignored.
+- `plugins/pr-review` supports an optional `require-evidence` action input that tells the reviewer to require end-to-end proof in the PR description that the code works; test output alone is not sufficient evidence.
+- The corresponding `REQUIRE_EVIDENCE` env flag is consumed by `plugins/pr-review/scripts/agent_script.py` and injected into the review prompt via `plugins/pr-review/scripts/prompt.py`.
+- `plugins/pr-review` exposes an `enable-uv-cache` input (default `'false'`) that toggles `setup-uv`'s GitHub Actions cache. Default stays off because a prompt-injected reviewer could poison a shared cache that higher-privilege workflows later consume; opt in only on single-tenant self-hosted runners. The README's "Caching and Security" section documents the threat model and recommends a host-level uv cache volume as the preferred alternative for self-hosted setups.
+- GitHub review suggestions that only delete lines can look empty in `PullRequestReviewComment.body`; the rendered content is available via `bodyText`/`bodyHTML`, so review-context formatting should fall back there before treating a suggestion as empty.
+- Prompt coverage for this behavior lives in `tests/test_pr_review_prompt.py`.
+- `plugins/pr-review`'s `collect-feedback` input should append a short thumbs up/down footer to the main GitHub review body via `agent_script.py` / `prompt.py`, rather than posting a separate PR comment. `evaluate_review.py` should read feedback from review-body reactions while still tolerating legacy issue-comment markers.
+
+
+## When uncertain
+
+- Prefer the official OpenHands docs on skills: https://docs.openhands.dev/overview/skills
+- Prefer the SDK skill guide: https://docs.openhands.dev/sdk/guides/skill

package/README.md

@@ -45,6 +45,16 @@ React logo components are isolated behind a separate export so data-only consume
 import { INTEGRATION_LOGOS } from "@openhands/extensions/integrations/logos";
 ```
 
+The package ships the whole repo, so the `skills/`, `plugins/`, and `marketplaces/` trees are available from the installed package. Resolve content files to a path, or import JSON manifests directly:
+
+```js
+// .md / .py / etc.: resolve to a path, then read with fs
+const skillPath = import.meta.resolve("@openhands/extensions/skills/code-review/SKILL.md");
+
+// .json: import directly
+import marketplace from "@openhands/extensions/marketplaces/openhands-extensions.json" with { type: "json" };
+```
+
 See [`integrations/README.md`](integrations/README.md), [`automations/README.md`](automations/README.md), and [`MIGRATION.md`](MIGRATION.md) for catalog-specific details.
 
 ## Extensions Catalog