@openhands/extensions 0.0.1-alpha → 0.2.0

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

@@ -0,0 +1,148 @@
+---
+name: github-pr-review
+description: Post PR review comments using the GitHub API with inline comments, suggestions, and priority labels.
+triggers:
+- /github-pr-review
+---
+
+# GitHub PR Review
+
+Post structured code review feedback using the GitHub API with inline comments on specific lines.
+
+## Key Rule: One API Call
+
+Bundle ALL comments into a **single review API call**. Do not post comments individually.
+
+## Posting a Review
+
+Use the GitHub CLI (`gh`) with a JSON input file. The `GITHUB_TOKEN` is automatically available.
+
+**Important**: Always use `--input` with a JSON file instead of `-F` flags. This avoids shell quoting issues with special characters in comment bodies (quotes, backticks, newlines, etc.) and eliminates the need for complex heredoc scripts.
+
+### Step 1: Create a JSON file
+
+```bash
+cat > /tmp/review.json << 'EOF'
+{
+  "commit_id": "{commit_sha}",
+  "event": "COMMENT",
+  "body": "Brief 1-3 sentence summary.",
+  "comments": [
+    {
+      "path": "path/to/file.py",
+      "line": 42,
+      "side": "RIGHT",
+      "body": "🟠 Important: Your comment here."
+    },
+    {
+      "path": "another/file.js",
+      "line": 15,
+      "side": "RIGHT",
+      "body": "🟡 Suggestion: Another comment."
+    }
+  ]
+}
+EOF
+```
+
+### Step 2: Post the review
+
+```bash
+gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/reviews --input /tmp/review.json
+```
+
+### Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `commit_id` | Commit SHA to comment on (use `git rev-parse HEAD`) |
+| `event` | `COMMENT`, `APPROVE`, or `REQUEST_CHANGES` |
+| `path` | File path as shown in the diff |
+| `line` | Line number in the NEW version (right side of diff) |
+| `side` | `RIGHT` for new/added lines, `LEFT` for deleted lines |
+| `body` | Comment text with priority label |
+
+### Multi-Line Comments
+
+For comments spanning multiple lines, add `start_line` to specify the range:
+
+```json
+{
+  "path": "path/to/file.py",
+  "start_line": 10,
+  "line": 12,
+  "side": "RIGHT",
+  "body": "🟡 Suggestion: Refactor this block:\n\n```suggestion\nline_one = \"new\"\nline_two = \"code\"\nline_three = \"here\"\n```"
+}
+```
+
+**Important**: The suggestion must have the same number of lines as the range (e.g., lines 10-12 = 3 lines).
+
+## Priority Labels
+
+Start each comment with a priority label. **Minimize nits** - leave minor style issues to linters.
+
+| Label | When to Use |
+|-------|-------------|
+| 🔴 **Critical** | Must fix: security vulnerabilities, bugs, data loss risks |
+| 🟠 **Important** | Should fix: logic errors, performance issues, missing error handling |
+| 🟡 **Suggestion** | Worth considering: significant improvements to clarity or maintainability |
+
+**Do NOT post 🟢 Nit or 🟢 Acceptable comments.** If code is fine, simply don't comment on it. Inline comments that say "this looks good" or "acceptable trade-off" are noise — they create review threads that must be resolved without providing actionable value.
+
+**Example:**
+```
+🟠 Important: This function doesn't handle None, which could cause an AttributeError.
+
+```suggestion
+if user is None:
+    raise ValueError("User cannot be None")
+```
+```
+
+## GitHub Suggestions
+
+For small code changes, use the suggestion syntax for one-click apply:
+
+~~~
+```suggestion
+improved_code_here()
+```
+~~~
+
+Use suggestions for: renaming, typos, small refactors (1-5 lines), type hints, docstrings.
+
+Avoid for: large refactors, architectural changes, ambiguous improvements.
+
+## Finding Line Numbers
+
+```bash
+# From diff header: @@ -old_start,old_count +new_start,new_count @@
+# Count from new_start for added/modified lines
+
+grep -n "pattern" filename     # Find line number
+head -n 42 filename | tail -1  # Verify line content
+```
+
+## Fallback: curl
+
+If `gh` is unavailable, use curl with the JSON file:
+
+```bash
+curl -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" \
+  -H "Accept: application/vnd.github+json" \
+  "https://api.github.com/repos/{owner}/{repo}/pulls/{pr_number}/reviews" \
+  -d @/tmp/review.json
+```
+
+## Summary
+
+1. Analyze the code and identify important issues (minimize nits)
+2. Write review data to a JSON file (e.g., `/tmp/review.json`)
+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
+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/github-pr-review/commands/github-pr-review.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Post PR review comments using the GitHub API with inline comments, suggestions, and priority labels.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/skills/github-pr-reviewer/.plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "github-pr-reviewer",
+  "version": "1.0.0",
+  "description": "Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed files, tests, and existing discussion via GitHub MCP, then posts a concise review highlighting risks, security issues, missing tests, and next steps.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "pull-request",
+    "review",
+    "code-review",
+    "automation",
+    "integration"
+  ]
+}

package/skills/github-pr-reviewer/README.md

@@ -0,0 +1,34 @@
+# GitHub PR Reviewer
+
+Create an automation that reviews GitHub pull requests on open or update.
+
+## Triggers
+
+This skill is activated by keywords:
+
+- `review pull requests`
+- `PR review automation`
+- `auto-review PRs`
+
+## Features
+
+- **Inspects PR diff, changed files, and test coverage**
+- **Posts review with correctness risks, security issues, missing tests**
+- **Supports event-based (webhook) or cron-based (polling) triggers**
+- **Configurable review tone (thorough, concise, friendly)**
+- **Auto-post or draft mode for human approval**
+
+## Prerequisites
+
+GitHub MCP installed in Settings → MCP
+
+## Quick Start
+
+Ask OpenHands:
+
+> "Set up a PR review automation for my myorg/backend repo that posts
+> concise reviews when PRs are opened"
+
+## See Also
+
+- [SKILL.md](SKILL.md) — Full setup workflow reference

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

@@ -0,0 +1,89 @@
+---
+name: github-pr-reviewer
+description: >
+  Create an automation that reviews GitHub pull requests when they are opened
+  or updated. Inspects the diff, changed files, tests, and existing discussion
+  via GitHub MCP, then posts a concise review highlighting risks, security
+  issues, missing tests, and next steps.
+triggers:
+  - /pr-reviewer:setup
+---
+
+# GitHub PR Reviewer Automation
+
+Set up a cron or event-triggered automation that reviews GitHub pull requests.
+
+---
+
+## Prerequisites
+
+### Required integration
+
+- **GitHub MCP** must be installed in Settings → MCP.
+
+### Information to collect
+
+Ask the user for:
+
+1. **Repositories** — which repos should be watched (e.g. `myorg/backend`, `myorg/frontend`)
+2. **Trigger type** — event-based (reacts to `pull_request.opened` / `pull_request.synchronize`) or cron-based polling
+3. **Review tone** — thorough, concise, or friendly
+4. **Auto-post or draft** — should reviews be posted as GitHub comments automatically, or saved as draft artifacts for human approval first?
+5. **Filters** — any label, branch, or author filters (e.g. skip drafts, only review PRs with `needs-review` label)
+
+---
+
+## Setup Workflow
+
+### Step 1 — Verify GitHub MCP access
+
+Confirm the GitHub MCP integration is working:
+```
+Use the GitHub MCP to list recent pull requests in one of the target repositories.
+```
+
+If it fails, tell the user to install the GitHub MCP integration first.
+
+### Step 2 — Determine trigger type
+
+**Event-based (recommended if publicly reachable):**
+Check `<RUNTIME_SERVICES>` for deployment reachability. If the deployment has a public URL, recommend an event trigger on `pull_request.opened` and `pull_request.synchronize`.
+
+**Cron-based (local/private deployments):**
+If the deployment is local, set up a cron schedule (e.g. every 5 minutes) that polls for recently updated PRs.
+
+### Step 3 — Build the review prompt
+
+Construct a prompt for the automation that includes:
+- The user's chosen repositories
+- Review focus areas (correctness, security, tests, maintainability)
+- Review tone preference
+- Whether to auto-post or draft
+
+### Step 4 — Create the automation
+
+Read the Automation backend URL and auth from `<RUNTIME_SERVICES>`:
+- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`
+- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`
+
+Use the **prompt preset** endpoint:
+```bash
+curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "GitHub PR Reviewer",
+    "prompt": "<constructed review prompt>",
+    "trigger": <trigger config from step 2>
+  }'
+```
+
+### Step 5 — Confirm
+
+Tell the user:
+> ✅ **GitHub PR Reviewer** is running!
+>
+> - Automation ID: `{id}`
+> - Repositories: `{repo list}`
+> - Trigger: `{trigger description}`
+> - Review style: `{tone}`, `{auto-post or draft}`

package/skills/github-pr-reviewer/commands/pr-reviewer:setup.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed files, tests, and existing discussion via GitHub MCP, then posts a concise review highlighting risks, security issues, missing tests, and next steps.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/skills/github-repo-monitor/.plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "github-repo-monitor",
+  "version": "1.0.0",
+  "description": "Create a cron automation that polls a GitHub repository for issue and PR comments containing a configurable trigger phrase (@OpenHands by default). Starts an OpenHands conversation with full issue/PR context, posts acknowledgement comments with a conversation link, and summarises results back to the issue/PR when the agent finishes.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "monitor",
+    "issues",
+    "pull-requests",
+    "trigger",
+    "cron",
+    "automation",
+    "integration"
+  ]
+}

package/skills/github-repo-monitor/README.md

@@ -0,0 +1,70 @@
+# GitHub Repository Monitor Skill
+
+An OpenHands skill that creates a cron automation to monitor a GitHub
+repository for issue and PR comments, routing them to OpenHands conversations
+and posting results back as GitHub comments.
+
+## What it does
+
+1. **Polls** a GitHub repository for new comments on issues and PRs.
+2. **Triggers** when a comment contains `@OpenHands` (configurable).
+3. **Creates** an OpenHands conversation pre-loaded with the full issue/PR
+   context — title, description, labels, and the last 10 comments.
+4. **Posts** a GitHub comment with a link to the conversation and an
+   AI-disclosure notice.
+5. **Forwards** follow-up trigger comments to the running conversation,
+   or re-opens it if it was previously closed.
+6. **Summarises** by posting the agent's final response back to the
+   issue/PR once the conversation finishes.
+
+## Files
+
+```
+github-repo-monitor/
+├── SKILL.md                  ← agent instructions (loaded automatically)
+├── README.md                 ← this file
+├── scripts/
+│   └── main.py               ← automation script template
+└── references/
+    ├── state-schema.md       ← JSON state file documentation
+    └── github-api.md         ← GitHub API endpoints and rate-limit notes
+```
+
+## Quick start
+
+Just tell OpenHands:
+
+> *"Set up a GitHub repository monitor for `owner/repo`"*
+
+The skill will walk through token verification, allowed-login selection,
+event-type selection, cron schedule, and automation creation automatically.
+
+## Requirements
+
+- `GITHUB_TOKEN` secret set in OpenHands Settings → Secrets
+  - Classic PAT: `repo` (private repos) or `public_repo` (public repos)
+  - Fine-grained PAT: Issues — Read and Write
+- The monitored repository must be accessible with that token
+
+## Configuration options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| Repository | (required) | `owner/repo` format |
+| Trigger phrase | `@OpenHands` | Case-insensitive string to watch for in comments |
+| Allowed GitHub logins | token owner only | Who may trigger conversations; use explicit logins or `*` for any non-bot commenter |
+| Event types | `issue_comment` | `issue_comment`, `pr_review_comment`, or both |
+| Cron schedule | `* * * * *` | Every minute; any valid 5-field cron expression |
+
+## State file
+
+The automation maintains a JSON state file at:
+```
+~/.openhands/workspaces/automation-state/github_poller_{automation_id}.json
+```
+
+See `references/state-schema.md` for the full schema.
+
+## Similar skills
+
+- `slack-channel-monitor` — same pattern applied to Slack channels