@openhands/extensions 0.2.0 → 0.4.0

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/github-repo-monitor/README.md

@@ -41,7 +41,7 @@ event-type selection, cron schedule, and automation creation automatically.
 
 ## Requirements
 
-- `GITHUB_TOKEN` secret set in OpenHands Settings → Secrets
+- `GITHUB_PERSONAL_ACCESS_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

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

@@ -45,13 +45,13 @@ before proceeding:
 
 | Secret name | Token type | Minimum permissions |
 |---|---|---|
-| `GITHUB_TOKEN` | Classic PAT | `repo` (private repos) or `public_repo` (public repos) |
-| `GITHUB_TOKEN` | Fine-grained PAT | Issues: Read and Write |
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` (private repos) or `public_repo` (public repos) |
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Issues: Read and Write |
 
 Check with:
 ```bash
 curl -s https://api.github.com/user \
-  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
   -H "Accept: application/vnd.github+json" \
   | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))"
 ```
@@ -71,12 +71,12 @@ function without GitHub credentials.
 
 Follow these steps in order.
 
-### Step 1  -  Verify GITHUB_TOKEN
+### Step 1  -  Verify GITHUB_PERSONAL_ACCESS_TOKEN
 
 Fetch the secret and run the `curl` check above.
 
 - If the secret is absent: tell the user
-  *"GITHUB_TOKEN is not set. Please add it in OpenHands Settings → Secrets
+  *"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in OpenHands Settings → Secrets
   (classic PAT with `repo` or `public_repo` scope, or a fine-grained PAT
   with Issues: Read and Write)."* Then stop.
 
@@ -92,7 +92,7 @@ Validate access and write permissions:
 
 ```bash
 curl -s "https://api.github.com/repos/{owner}/{repo}" \
-  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
   -H "Accept: application/vnd.github+json" \
   | python3 -c "
 import json, sys
@@ -123,7 +123,7 @@ Record as `TRIGGER_PHRASE`. Default: `"@openhands"`.
 ### Step 4  -  Collect allowed GitHub logins
 
 Ask the user: *"Which GitHub users may trigger this automation?
-Press Enter to allow only the authenticated `GITHUB_TOKEN` owner.
+Press Enter to allow only the authenticated `GITHUB_PERSONAL_ACCESS_TOKEN` owner.
 You may also provide comma-separated GitHub logins, or `*` to allow any
 non-bot commenter on the monitored repository."*
 
@@ -261,7 +261,7 @@ Tell the user:
 Each cron run executes `main.py`, which:
 
 1. **Loads state** from the JSON file (see `references/state-schema.md`).
-2. **Resolves and validates GITHUB_TOKEN** — aborts immediately if absent or invalid.
+2. **Resolves and validates GITHUB_PERSONAL_ACCESS_TOKEN** — aborts immediately if absent or invalid.
 3. **Polls for new events** since the previous `last_poll` timestamp:
    - `GET /repos/{owner}/{repo}/issues/comments?since=…` for `issue_comment`
    - `GET /repos/{owner}/{repo}/pulls/comments?since=…` for `pr_review_comment`
@@ -307,7 +307,7 @@ Each cron run executes `main.py`, which:
 
 | Symptom | Likely cause | Fix |
 |---|---|---|
-| Bot doesn't respond to comments | `GITHUB_TOKEN` missing or wrong scopes | Verify token with `curl /user`; check scopes in Step 1 |
+| Bot doesn't respond to comments | `GITHUB_PERSONAL_ACCESS_TOKEN` missing or wrong scopes | Verify token with `curl /user`; check scopes in Step 1 |
 | "Bad credentials" in run logs | Token expired | Rotate token and update the secret in Settings |
 | 404 on repo access | Repo name wrong or token has no access | Re-check `owner/repo` spelling; add token as collaborator |
 | Comments posted but no conversation created | Agent server URL wrong | Check `OPENHANDS_URL` secret and `AGENT_SERVER_URL` env var |

package/skills/github-repo-monitor/references/github-api.md

@@ -10,7 +10,7 @@ the GitHub Repository Monitor automation.
 All requests use Bearer authentication:
 
 ```
-Authorization: Bearer {GITHUB_TOKEN}
+Authorization: Bearer {GITHUB_PERSONAL_ACCESS_TOKEN}
 Accept: application/vnd.github+json
 X-GitHub-Api-Version: 2022-11-28
 ```
@@ -37,7 +37,7 @@ X-GitHub-Api-Version: 2022-11-28
 
 ```bash
 curl -I https://api.github.com/user \
-  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
   | grep -i x-oauth-scopes
 # X-OAuth-Scopes: repo, public_repo
 ```
@@ -209,7 +209,7 @@ Typical usage: **< 20 requests/hour** for a quiet repo,
 Check remaining quota with:
 ```bash
 curl -s https://api.github.com/rate_limit \
-  -H "Authorization: Bearer $GITHUB_TOKEN" \
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
   | python3 -c "
 import json, sys
 d = json.load(sys.stdin)

package/skills/github-repo-monitor/scripts/main.py

@@ -18,7 +18,7 @@ Configuration constants are embedded at automation-creation time by the skill.
 See SKILL.md for the full setup workflow.
 
 Required secrets (set in OpenHands Settings → Secrets):
-  GITHUB_TOKEN  - Personal Access Token
+  GITHUB_PERSONAL_ACCESS_TOKEN  - Personal Access Token
                   Classic PAT:       'repo' scope (private) or 'public_repo' (public)
                   Fine-grained PAT:  Issues: Read and Write
 
@@ -40,7 +40,7 @@ from urllib.parse import urlencode
 REPO = "owner/repo"                     # e.g. "microsoft/vscode"
 TRIGGER_PHRASE = "@openhands"           # case-insensitive
 EVENT_TYPES = ["issue_comment"]         # e.g. ["issue_comment", "pr_review_comment"]
-# Who may trigger conversations. Default is the authenticated GITHUB_TOKEN owner.
+# Who may trigger conversations. Default is the authenticated GITHUB_PERSONAL_ACCESS_TOKEN owner.
 # Use ["*"] to allow any non-bot commenter, or explicit logins like ["octocat"].
 ALLOWED_GITHUB_LOGINS = ["<TOKEN_OWNER>"]
 DEFAULT_OPENHANDS_URL = "http://localhost:8000"
@@ -207,15 +207,15 @@ def _github_paginate(token: str, path: str, params: dict | None = None) -> list:
 
 
 def _resolve_github_token() -> str:
-    """Fetch GITHUB_TOKEN from secrets.  Raises RuntimeError if absent."""
+    """Fetch GITHUB_PERSONAL_ACCESS_TOKEN from secrets.  Raises RuntimeError if absent."""
     try:
-        token = get_secret("GITHUB_TOKEN")
+        token = get_secret("GITHUB_PERSONAL_ACCESS_TOKEN")
         if token:
             return token
     except Exception:
         pass
     raise RuntimeError(
-        "GITHUB_TOKEN secret is not set. "
+        "GITHUB_PERSONAL_ACCESS_TOKEN secret is not set. "
         "Go to OpenHands Settings → Secrets and add your GitHub Personal Access Token."
     )
 
@@ -231,7 +231,7 @@ def _verify_token_and_repo(token: str, repo: str) -> str:
     except urllib.error.HTTPError as exc:
         if exc.code == 401:
             raise RuntimeError(
-                "GITHUB_TOKEN is invalid or expired. "
+                "GITHUB_PERSONAL_ACCESS_TOKEN is invalid or expired. "
                 "Update it in OpenHands Settings → Secrets."
             )
         raise RuntimeError(f"GitHub /user check failed: {exc.code}")
@@ -247,13 +247,13 @@ def _verify_token_and_repo(token: str, repo: str) -> str:
     except urllib.error.HTTPError as exc:
         if exc.code == 404:
             raise RuntimeError(
-                f"Repository '{repo}' not found or not accessible with the current GITHUB_TOKEN. "
+                f"Repository '{repo}' not found or not accessible with the current GITHUB_PERSONAL_ACCESS_TOKEN. "
                 "Check the repo name (format: owner/repo) and token permissions."
             )
         if exc.code == 403:
             raise RuntimeError(
                 f"Access denied to repository '{repo}'. "
-                "Ensure GITHUB_TOKEN has the required permissions."
+                "Ensure GITHUB_PERSONAL_ACCESS_TOKEN has the required permissions."
             )
         raise RuntimeError(f"GitHub /repos/{repo} check failed: {exc.code}")
 
@@ -268,7 +268,7 @@ def _verify_token_and_repo(token: str, repo: str) -> str:
         # Private repo: must have push access or the 'repo' classic-PAT scope.
         if not can_push and not has_repo_scope and scopes:
             raise RuntimeError(
-                f"GITHUB_TOKEN cannot post comments to private repository '{repo}'. "
+                f"GITHUB_PERSONAL_ACCESS_TOKEN cannot post comments to private repository '{repo}'. "
                 "A classic PAT needs the 'repo' scope; "
                 "a fine-grained PAT needs 'Issues: Read and Write' permission."
             )
@@ -276,7 +276,7 @@ def _verify_token_and_repo(token: str, repo: str) -> str:
         # Public repo: need at minimum 'public_repo' scope or push access.
         if scopes and not (can_push or has_public_repo_scope or has_repo_scope):
             raise RuntimeError(
-                f"GITHUB_TOKEN cannot post comments to public repository '{repo}'. "
+                f"GITHUB_PERSONAL_ACCESS_TOKEN cannot post comments to public repository '{repo}'. "
                 "A classic PAT needs the 'public_repo' scope; "
                 "a fine-grained PAT needs 'Issues: Read and Write' permission."
             )
@@ -591,7 +591,7 @@ def _build_initial_prompt(ctx: dict, trigger_comment: dict, event_type: str) ->
         f"\nTriggering comment by @{trigger_author}:{path_info}\n"
         f"---\n{trigger_body}\n---\n"
         f"\nPlease analyse the request and take the appropriate action.\n"
-        f"The GITHUB_TOKEN secret is available if you need to interact with the "
+        f"The GITHUB_PERSONAL_ACCESS_TOKEN secret is available if you need to interact with the "
         f"GitHub API (fetch the PR diff, create commits, update labels, etc.).\n"
         f"When you are finished, summarise what you did clearly — that summary "
         f"will be posted back to the GitHub {item_type} as a comment."

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;