@openhands/extensions 0.3.0 → 0.4.0

package/.release-please-manifest.json

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

package/README.md

@@ -60,7 +60,7 @@ See [`integrations/README.md`](integrations/README.md), [`automations/README.md`
 ## Extensions Catalog
 
 <!-- BEGIN AUTO-GENERATED CATALOG -->
-This repository contains **2 marketplace(s)** with **56 extensions** (46 skills, 10 plugins).
+This repository contains **2 marketplace(s)** with **57 extensions** (47 skills, 10 plugins).
 
 ### large-codebase
 
@@ -79,7 +79,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases
 
 Official skills and plugins for OpenHands — the open-source AI software engineer.
 
-**52 extensions** (44 skills, 8 plugins)
+**53 extensions** (45 skills, 8 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
@@ -100,6 +100,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | flarglebargle | skill | A test skill that responds to the magic word 'flarglebargle' with a compliment. Use for testing skill activation and ... | — |
 | frontend-design | skill | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks ... | — |
 | github | skill | Interact with GitHub repositories, pull requests, issues, and workflows using the GITHUB_TOKEN environment variable a... | — |
+| github-actions | skill | Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating wo... | — |
 | github-pr-review | skill | Post structured PR reviews to GitHub with inline comments/suggestions in a single API call. | `/github-pr-review` |
 | github-pr-reviewer | skill | Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed fi... | `/pr-reviewer:setup` |
 | github-repo-monitor | skill | Create a cron automation that polls a GitHub repository for issue and PR comments containing a configurable trigger p... | `/github-monitor:poll` |

package/automations/catalog/github-pr-reviewer.json

@@ -1,6 +1,6 @@
 {
   "id": "github-pr-reviewer",
-  "name": "GitHub PR review copilot",
+  "name": "GitHub Code Review Agent",
   "category": "Code review",
   "description": "Watch pull requests, inspect the diff, and leave a concise review with risks and suggested follow-ups.",
   "requiredIntegrationIds": [

package/automations/catalog/github-repo-monitor.json

@@ -7,5 +7,5 @@
   "popularityRank": 98,
   "estimatedSetupMinutes": 5,
   "prompt": "/github-monitor:poll",
-  "exampleImplementation": "Trigger: cron, every minute (configurable)\nRequired secret: GITHUB_TOKEN\n\n1. Poll GitHub for new issue and PR comments since the last run.\n2. Match comments containing the trigger phrase (case-insensitive, default: @OpenHands).\n3. Post an acknowledgment comment with a link to the new OpenHands conversation.\n4. Forward follow-up replies in the same thread to the running conversation.\n5. Post the agent's final response back to GitHub when the conversation completes."
+  "exampleImplementation": "Trigger: cron, every minute (configurable)\nRequired secret: GITHUB_PERSONAL_ACCESS_TOKEN\n\n1. Poll GitHub for new issue and PR comments since the last run.\n2. Match comments containing the trigger phrase (case-insensitive, default: @OpenHands).\n3. Post an acknowledgment comment with a link to the new OpenHands conversation.\n4. Forward follow-up replies in the same thread to the running conversation.\n5. Post the agent's final response back to GitHub when the conversation completes."
 }

package/marketplaces/openhands-extensions.json

@@ -238,6 +238,19 @@
         "workflows"
       ]
     },
+    {
+      "name": "github-actions",
+      "source": "./skills/github-actions",
+      "description": "Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating workflows, or troubleshooting GitHub Actions.",
+      "category": "integration",
+      "keywords": [
+        "github-actions",
+        "workflows",
+        "ci-cd",
+        "automation",
+        "actions"
+      ]
+    },
     {
       "name": "github-pr-review",
       "source": "./skills/github-pr-review",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",

package/plugins/issue-duplicate-checker/action.yml

@@ -258,7 +258,7 @@ runs:
           if: inputs.mode == 'issue-check' && steps.parsed_result.outputs.should_comment == 'true'
           uses: actions/github-script@v9
           env:
-              ACTION_SCRIPT: ${{ github.action_path }}/scripts/post_duplicate_notice.js
+              ACTION_SCRIPT: ${{ github.action_path }}/scripts/post_duplicate_notice.cjs
               ISSUE_NUMBER: ${{ inputs.issue-number }}
               SUMMARY: ${{ steps.parsed_result.outputs.summary }}
               CANDIDATE_ISSUES_JSON: ${{ steps.parsed_result.outputs.candidate_issues_json }}
@@ -341,7 +341,7 @@ runs:
           if: inputs.mode == 'remove-label'
           uses: actions/github-script@v9
           env:
-              ACTION_SCRIPT: ${{ github.action_path }}/scripts/remove_duplicate_candidate_label.js
+              ACTION_SCRIPT: ${{ github.action_path }}/scripts/remove_duplicate_candidate_label.cjs
           with:
               github-token: ${{ inputs.github-token }}
               script: |

package/plugins/pr-review/README.md

@@ -69,7 +69,7 @@ Add the following secrets in your repository settings (**Settings → Secrets an
 | `GITHUB_TOKEN` | Auto | Provided automatically by GitHub Actions |
 | `LMNR_SKILLS_API_KEY` | No | Laminar API key (org-level secret; mapped to `LMNR_PROJECT_API_KEY` env var in workflows) |
 
-**Note**: For repositories that need to post review comments from a bot account, use `ALLHANDS_BOT_GITHUB_PAT` instead of `GITHUB_TOKEN`.
+**Note**: To post review comments from a bot account instead of `GITHUB_TOKEN`, use a bot token scoped to the repository's trust boundary. On **public** repositories, use `OPENHANDS_BOT_GITHUB_PAT_PUBLIC` — a fine-grained token limited to public repositories. On **private** repositories, use a bot token scoped to that repository. Never give a public repository a token that can reach private repositories.
 
 ### 3. Customize the Workflow (Optional)
 

package/plugins/qa-changes/action.yml

@@ -119,6 +119,8 @@ runs:
       env:
         LLM_API_KEY: ${{ inputs.llm-api-key }}
         GITHUB_TOKEN: ${{ inputs.github-token }}
+        GITHUB_EVENT_PULL_REQUEST_TITLE: ${{ github.event.pull_request.title }}
+        INPUTS_LLM_MODEL: ${{ inputs.llm-model }}
       run: |
         if [ -z "$LLM_API_KEY" ]; then
           echo "Error: llm-api-key is required."
@@ -130,9 +132,9 @@ runs:
         fi
 
         echo "PR Number: ${{ github.event.pull_request.number }}"
-        echo "PR Title: ${{ github.event.pull_request.title }}"
+        echo "PR Title: $GITHUB_EVENT_PULL_REQUEST_TITLE"
         echo "Repository: ${{ github.repository }}"
-        echo "LLM model: ${{ inputs.llm-model }}"
+        echo "LLM model: $INPUTS_LLM_MODEL"
 
     - name: Run QA validation
       if: steps.preflight.outputs.skip != 'true'

package/plugins/release-notes/action.yml

@@ -109,9 +109,10 @@ runs:
           shell: bash
           env:
               GITHUB_TOKEN: ${{ inputs.github-token }}
+              INPUTS_TAG: ${{ inputs.tag }}
           run: |
               if [ -f release_notes.md ]; then
-                echo "Updating release notes for tag ${{ inputs.tag }}"
-                gh release edit "${{ inputs.tag }}" --notes-file release_notes.md || \
+                echo "Updating release notes for tag $INPUTS_TAG"
+                gh release edit "$INPUTS_TAG" --notes-file release_notes.md || \
                   echo "Note: Could not update release. Release may not exist yet."
               fi

package/plugins/release-notes/workflows/release-notes.yml

@@ -38,11 +38,14 @@ jobs:
 
             - name: Determine tag
               id: get-tag
+              env:
+                GITHUB_EVENT_INPUTS_TAG: ${{ github.event.inputs.tag }}
+                GITHUB_REF_NAME: ${{ github.ref_name }}
               run: |
                   if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-                    echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT
+                    echo "tag=$GITHUB_EVENT_INPUTS_TAG" >> $GITHUB_OUTPUT
                   else
-                    echo "tag=${{ github.ref_name }}" >> $GITHUB_OUTPUT
+                    echo "tag=$GITHUB_REF_NAME" >> $GITHUB_OUTPUT
                   fi
 
             - name: Generate Release Notes
@@ -57,10 +60,13 @@ jobs:
                   github-token: ${{ secrets.GITHUB_TOKEN }}
 
             - name: Display generated notes
+              env:
+                TAG: ${{ steps.get-tag.outputs.tag }}
+                PREVIOUS_TAG: ${{ steps.release-notes.outputs.previous-tag }}
               run: |
-                  echo "## Release Notes for ${{ steps.get-tag.outputs.tag }}"
+                  echo "## Release Notes for $TAG"
                   echo ""
-                  echo "Previous tag: ${{ steps.release-notes.outputs.previous-tag }}"
+                  echo "Previous tag: $PREVIOUS_TAG"
                   echo "Commits: ${{ steps.release-notes.outputs.commit-count }}"
                   echo "Contributors: ${{ steps.release-notes.outputs.contributor-count }}"
                   echo "New contributors: ${{ steps.release-notes.outputs.new-contributor-count }}"

package/plugins/vulnerability-remediation/README.md

@@ -90,12 +90,14 @@ on:
 
 ### Optional: Use a Bot Account
 
-For better PR attribution, use a bot PAT:
+For better PR attribution, use a bot PAT scoped to the repository's trust boundary. On **public** repositories, use the public-scoped token:
 
 ```yaml
-github-token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT || secrets.GITHUB_TOKEN }}
+github-token: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC || secrets.GITHUB_TOKEN }}
 ```
 
+On **private** repositories, use a bot token scoped to that repository instead. Never give a public repository a token that can reach private repositories.
+
 ## Usage
 
 ### Automatic Scheduled Scans

package/plugins/vulnerability-remediation/action.yml

@@ -96,6 +96,10 @@ runs:
           env:
               LLM_API_KEY: ${{ inputs.llm-api-key }}
               GITHUB_TOKEN: ${{ inputs.github-token }}
+              INPUTS_EXTENSIONS_VERSION: ${{ inputs.extensions-version }}
+              INPUTS_LLM_MODEL: ${{ inputs.llm-model }}
+              INPUTS_SEVERITY_THRESHOLD: ${{ inputs.severity-threshold }}
+              INPUTS_MAX_VULNERABILITIES: ${{ inputs.max-vulnerabilities }}
           run: |
               if [ -z "$LLM_API_KEY" ]; then
                 echo "Error: llm-api-key is required."
@@ -108,10 +112,10 @@ runs:
               fi
 
               echo "Repository: ${{ github.repository }}"
-              echo "Extensions Version: ${{ inputs.extensions-version }}"
-              echo "LLM Model: ${{ inputs.llm-model }}"
-              echo "Severity Threshold: ${{ inputs.severity-threshold }}"
-              echo "Max Vulnerabilities: ${{ inputs.max-vulnerabilities }}"
+              echo "Extensions Version: $INPUTS_EXTENSIONS_VERSION"
+              echo "LLM Model: $INPUTS_LLM_MODEL"
+              echo "Severity Threshold: $INPUTS_SEVERITY_THRESHOLD"
+              echo "Max Vulnerabilities: $INPUTS_MAX_VULNERABILITIES"
 
         - name: Run vulnerability scan
           id: scan

package/pyproject.toml

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

package/scripts/sync_extensions.py

@@ -143,7 +143,8 @@ def collect_needed_commands() -> list[CommandSpec]:
             meta = parse_frontmatter(skill_md.read_text())
             desc = str(meta.get("description", ""))
             for trigger in slash_triggers(meta):
-                cmd_name = trigger.lstrip("/")
+                # Replace colons with dashes for cross-platform filename compatibility
+                cmd_name = trigger.lstrip("/").replace(":", "-")
                 cmd_path = skill_dir / "commands" / f"{cmd_name}.md"
                 needed.append(CommandSpec(path=cmd_path, trigger=trigger, description=desc))
     return needed

package/skills/github-actions/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "github-actions",
+  "version": "1.0.0",
+  "description": "Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating workflows, or troubleshooting GitHub Actions.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github-actions",
+    "workflows",
+    "ci-cd",
+    "automation",
+    "actions"
+  ]
+}

package/skills/github-actions/README.md

@@ -0,0 +1,190 @@
+# GitHub Actions Skill
+
+A skill focused on **effectiveness** when working with GitHub Actions — monitoring runs, reading logs, and developing actions with confidence rather than guessing.
+
+## Overview
+
+This skill provides guidance for:
+- Creating and structuring workflows
+- Building custom composite and reusable actions
+- Testing actions locally (before burning CI minutes) and in CI
+- Debugging failed workflows from real evidence (logs), not assumptions
+- Avoiding common pitfalls around permissions, secrets, and fork PRs
+
+## When to Use This Skill
+
+- Creating new GitHub Actions workflows
+- Building custom composite or reusable actions
+- Debugging workflow failures
+- Setting up CI/CD pipelines
+- Troubleshooting permission or secret issues
+- Testing actions before merging to main
+
+## Cost Awareness
+
+Every workflow run consumes CI minutes (billed minutes on private repos, shared capacity on public ones).
+Plan before you push:
+
+- Prefer one targeted commit that exercises the change over multiple speculative pushes
+- Use `workflow_dispatch` with inputs to manually trigger only what you need
+- Use `paths:` filters and `if:` conditions so jobs only run when relevant
+- Run with `act` locally before opening a PR when feasible
+- Cancel obsolete runs with `concurrency:` groups (don't pay for runs you've already invalidated)
+- Use the smallest matrix that proves the change works; expand only if needed
+
+## Develop With Confidence: The Loop
+
+Don't change → push → hope. Use this loop:
+
+1. **Read** the existing workflow / action carefully. Note triggers, permissions, inputs, env, and secrets.
+2. **Reproduce locally** with `act` when possible (see below).
+3. **Add visibility** — debug steps that print non-secret inputs, refs, and intermediate state.
+4. **Push a single focused commit**, then watch the run live.
+5. **Read the full failed-job log** (not just the summary) before editing.
+6. **Form a hypothesis from the log**, change the smallest thing that tests it, push, watch again.
+
+## Monitoring Runs With `gh`
+
+```bash
+# Watch the most recent run from the current branch in real time
+gh run watch
+
+# Watch a specific run
+gh run watch <run-id>
+
+# Auto-refresh PR checks until they finish (every 10s)
+gh pr checks <pr-number> --watch --interval 10
+
+# List recent runs for the repo / branch
+gh run list --branch <branch> --limit 10
+
+# Get the run ID for the latest run on a branch
+gh run list --branch <branch> --limit 1 --json databaseId --jq '.[0].databaseId'
+```
+
+## Reading Logs (Don't Guess)
+
+```bash
+# Full log for a run
+gh run view <run-id> --log
+
+# Just the failed steps (much shorter)
+gh run view <run-id> --log-failed
+
+# Log for a specific job (useful for matrix builds)
+gh run view <run-id> --log --job <job-id>
+
+# List jobs for a run to find the job ID
+gh run view <run-id> --json jobs --jq '.jobs[] | {id, name, conclusion}'
+
+# Rerun only the failed jobs (avoid paying to rerun green ones)
+gh run rerun <run-id> --failed
+```
+
+When a step fails, look for:
+- The exact command that exited non-zero (above the `##[error]` line)
+- The shell — bash on Linux, `pwsh` on Windows runners — error messages differ
+- Values printed by your debug step; compare against what the workflow *thought* it was passing in
+
+## Adding Visibility to Actions
+
+When creating a new action or hitting a tricky bug, add debug steps. Don't leave them in indefinitely — remove or guard them with `if: runner.debug == '1'` once the issue is understood.
+
+```yaml
+steps:
+  # Print non-secret inputs and context at the start
+  - name: Debug - inputs and context
+    if: runner.debug == '1' || inputs.debug == 'true'
+    run: |
+      echo "Event: ${{ github.event_name }}"
+      echo "Ref:   ${{ github.ref }}"
+      echo "SHA:   ${{ github.sha }}"
+      echo "Actor: ${{ github.actor }}"
+      echo "PWD:   $(pwd)"
+      echo "Input.my-param: ${{ inputs.my-param }}"
+      echo "Files:"
+      ls -la
+
+  # ... your real steps ...
+
+  # Verify outcome before the job ends
+  - name: Debug - verify outputs
+    if: always() && (runner.debug == '1' || inputs.debug == 'true')
+    run: |
+      echo "Generated files:"
+      ls -la dist/ || echo "dist/ not found"
+```
+
+To enable `runner.debug == '1'` for a single run, re-run the workflow with **"Enable debug logging"** checked, or set the repo secret `ACTIONS_RUNNER_DEBUG=true`.
+
+**Never** echo `${{ secrets.* }}` — GitHub masks them, but encoded forms (base64, hex, JSON-wrapped) can leak through.
+
+## Testing Locally With `act`
+
+`act` ([nektos/act](https://github.com/nektos/act)) runs workflows in Docker locally (Docker must be installed and running). Use it to iterate without burning CI minutes.
+
+```bash
+# Run the default push event
+act
+
+# Simulate a pull_request event
+act pull_request
+
+# Run a specific job
+act -j build
+
+# Pass secrets
+act -s GITHUB_TOKEN="$GITHUB_TOKEN"
+
+# Use a larger image closer to GitHub's runner
+act -P ubuntu-latest=catthehacker/ubuntu:full-latest
+```
+
+Caveats: `act` does not perfectly emulate GitHub's runners. Things that may differ: pre-installed tools, `GITHUB_TOKEN` permissions, OIDC, the `secrets.GITHUB_TOKEN` value, and macOS/Windows runners. Treat green-on-`act` as a strong signal, not a guarantee.
+
+## Testing Custom Actions Requires Merge to Main
+
+A repository-local custom action referenced as `uses: ./.github/actions/my-action` works from any branch, but:
+
+- A custom action published as `uses: owner/repo/action@ref` must have the action's files **on `ref`** to be resolvable
+- `@main` or `@v1` must already exist when the workflow that consumes it runs
+- This is why a brand-new action typically must land on `main` first, then be consumed from feature branches that reference `@main` (or a tag)
+
+If you need to iterate on an action and its consumer together, point `uses:` at a SHA on your branch, or develop the action via the local `./.github/actions/…` path until it's stable.
+
+## Common Pitfalls
+
+1. **Custom action not found from a PR** — the action's ref doesn't exist yet. Merge to `main` (or push a tag), then consume.
+2. **`GITHUB_TOKEN` permissions** — defaults can be read-only. Set `permissions:` explicitly at the workflow or job level.
+3. **`pull_request` vs `pull_request_target`** — `pull_request` runs in the fork's context (no secrets); `pull_request_target` runs with repo secrets against the base — **dangerous** if you check out PR code and execute it. Don't.
+4. **Secrets in fork PRs** — even non-`*_target` workflows hide secrets from forks. Don't design workflows that require secrets to run on community PRs.
+5. **`schedule:` triggers only fire from the default branch** — a `schedule:` trigger added in a PR only fires after it lands on the default branch; `workflow_dispatch` similarly won't appear in the Actions tab UI until merged to default (though it can be triggered via API on any branch); `pull_request`-triggered workflows do run on the PR that introduces them.
+6. **Path filters are OR, not AND** — any matching path triggers; you can't require all paths.
+7. **Matrix `fail-fast: true`** (default) cancels other matrix legs on first failure — turn off when you need full coverage.
+8. **Artifacts** — files don't persist between jobs unless uploaded via `actions/upload-artifact` and downloaded in the consuming job.
+9. **`env:` scope** — env at workflow, job, and step levels all exist. Step-level shadows job-level shadows workflow-level. Surprises follow if you forget.
+10. **Pin versions** — use `@v4` (or better, a SHA) rather than `@main`. Floating refs break builds when upstream changes.
+
+## Best Practices
+
+1. **Pin action versions** — `@v4` or SHA, not `@main`
+2. **Least privilege** — set `permissions:` to the minimum needed
+3. **Debug steps when introducing or debugging** — remove or gate them with `runner.debug` afterward
+4. **Cache dependencies** — `actions/cache` saves real minutes
+5. **Concurrency** — cancel obsolete runs:
+   ```yaml
+   concurrency:
+     group: ${{ github.workflow }}-${{ github.ref }}
+     cancel-in-progress: true
+   ```
+6. **Timeouts** — set `timeout-minutes:` on jobs that can hang
+7. **Fail loudly** — `set -euo pipefail` in non-trivial bash steps
+8. **Document non-obvious triggers/inputs** at the top of the workflow file
+
+## Resources
+
+- [GitHub Actions documentation](https://docs.github.com/en/actions)
+- [`act` — run actions locally](https://github.com/nektos/act)
+- [`gh run` CLI reference](https://cli.github.com/manual/gh_run)
+- [github skill](https://github.com/OpenHands/extensions/tree/main/skills/github) — GitHub API, PRs, issues, and repos
+- [github-pr-review skill](https://github.com/OpenHands/extensions/tree/main/skills/github-pr-review) — post structured code reviews via the GitHub API

package/skills/github-actions/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: github-actions
+description: Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating workflows, or troubleshooting GitHub Actions.
+triggers:
+- github actions
+- github workflow
+- actions workflow
+- gh actions
+- .github/workflows
+---
+
+# GitHub Actions Guide
+
+## Critical Rules
+
+**Custom Action Deployment:**
+- New custom actions MUST be merged to the main branch before they can be used
+- After the initial merge, they should be tested from feature branches
+
+**Debug Steps:**
+Add debug steps that print non-secret parameters when:
+- Creating a new action, OR
+- Troubleshooting a particularly tricky issue
+
+(Not required for every workflow - use when needed)
+
+## Effectiveness Principles
+
+Actions cost CI minutes. Be deliberate, not iterative:
+
+1. **Monitor, don't poll** - use `gh run watch` / `gh pr checks --watch` to follow runs live
+2. **Read logs, don't guess** - fetch the failed job's log before changing code
+3. **Print actual values** - debug steps reveal the real `inputs`/`github` context, not your assumptions
+4. **Test locally first** - `act` runs workflows on your machine and avoids burning CI minutes
+5. **Plan the smallest reproduction** - one job, minimal matrix, narrow trigger before scaling up
+
+See [README.md](README.md) for the full debugging workflow, `gh` commands, and YAML debug-step examples.
+
+## Key Gotchas
+
+1. **Secrets unavailable in fork PRs** - `pull_request` has no secrets for forks; `pull_request_target` does but **never check out or execute fork PR code inside it** (RCE with write permissions)
+2. **Pin action versions** - Use `@v4` or SHA, not `@main` (prevents breaking changes)
+3. **Explicit permissions** - Set `permissions:` block for GITHUB_TOKEN operations
+4. **Artifacts for job-to-job data** - Files don't persist between jobs without `upload-artifact`/`download-artifact`

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.js

@@ -159,6 +159,18 @@ export const SKILLS_CATALOG = [
     ],
     "content": "You have access to an environment variable, `GITHUB_TOKEN`, which allows you to interact with\nthe GitHub API.\n\n<IMPORTANT>\nYou can use `curl` with the `GITHUB_TOKEN` to interact with GitHub's API.\nALWAYS use the GitHub API for operations instead of a web browser.\nALWAYS use the `create_pr` tool to open a pull request\nIf the user asks you to check GitHub Actions status, first try to use `gh` to work with workflows, and only fallback to basic API calls if that fails.\nExamples:\n- `gh run watch` (https://cli.github.com/manual/gh_run_watch) to monitor workflow runs\n- `gh pr checks 200 --watch --interval 10` to check until completed.\n</IMPORTANT>\n\nIf you encounter authentication issues when pushing to GitHub (such as password prompts or permission errors), the old token may have expired. In such case, update the remote URL to include the current token: `git remote set-url origin https://${GITHUB_TOKEN}@github.com/username/repo.git`\n\nHere are some instructions for pushing, but ONLY do this if the user asks you to:\n* NEVER push directly to the `main` or `master` branch\n* Git config (username and email) is pre-set. Do not modify.\n* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.\n* Use the `create_pr` tool to create a pull request, if you haven't already\n* Once you've created your own branch or a pull request, continue to update it. Do NOT create a new one unless you are explicitly asked to. Update the PR title and description as necessary, but don't change the branch name.\n* Use the main branch as the base branch, unless the user requests otherwise\n* After opening or updating a pull request, send the user a short message with a link to the pull request.\n* Do NOT mark a pull request as ready to review unless the user explicitly says so\n* Do all of the above in as few steps as possible. E.g. you could push changes with one step by running the following bash commands:\n```bash\ngit remote -v && git branch # to find the current org, repo and branch\ngit checkout -b create-widget && git add . && git commit -m \"Create widget\" && git push -u origin create-widget\n```\n\n## Handling Review Comments\n\n- Critically evaluate each review comment before acting on it. Not all feedback is worth implementing:\n  - Does it fix a real bug or improve clarity significantly?\n  - Does it align with the project's engineering principles (simplicity, maintainability)?\n  - Is the suggested change proportional to the benefit, or does it add unnecessary complexity?\n- It's acceptable to respectfully decline suggestions that add verbosity without clear benefit, over-engineer for hypothetical edge cases, or contradict the project's pragmatic approach.\n- After addressing (or deciding not to address) inline review comments, mark the corresponding review threads as resolved.\n- Before resolving a thread, leave a reply comment that either explains the reason for dismissing the feedback or references the specific commit (e.g., commit SHA) that addressed the issue.\n- Prefer resolving threads only once fixes are pushed or a clear decision is documented.\n- Use the GitHub GraphQL API to reply to and resolve review threads (see below).\n- After making changes to a PR, verify the title and description still match the content. Update them if the scope, features, or intent changed.\n\n## Resolving Review Threads via GraphQL\n\nTo resolve existing review threads programmatically:\n\n1. Get the thread IDs (replace `<OWNER>`, `<REPO>`, `<PR_NUMBER>`):\n```bash\ngh api graphql -f query='\n{\n  repository(owner: \"<OWNER>\", name: \"<REPO>\") {\n    pullRequest(number: <PR_NUMBER>) {\n      reviewThreads(first: 20) {\n        nodes {\n          id\n          isResolved\n          comments(first: 1) {\n            nodes { body }\n          }\n        }\n      }\n    }\n  }\n}'\n```\n\n2. Reply to the thread explaining how the feedback was addressed:\n```bash\ngh api graphql -f query='\nmutation {\n  addPullRequestReviewThreadReply(input: {\n    pullRequestReviewThreadId: \"<THREAD_ID>\"\n    body: \"Fixed in <COMMIT_SHA>\"\n  }) {\n    comment { id }\n  }\n}'\n```\n\n3. Resolve the thread:\n```bash\ngh api graphql -f query='\nmutation {\n  resolveReviewThread(input: {threadId: \"<THREAD_ID>\"}) {\n    thread { isResolved }\n  }\n}'\n```\n\n4. Get the failed workflow run ID and rerun it:\n```bash\n# Find the run ID from the failed check URL, or use:\ngh run list --repo <OWNER>/<REPO> --branch <BRANCH> --limit 5\n\n# Rerun failed jobs\ngh run rerun <RUN_ID> --repo <OWNER>/<REPO> --failed\n```"
   },
+  {
+    "name": "github-actions",
+    "description": "Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating workflows, or troubleshooting GitHub Actions.",
+    "triggers": [
+      "github actions",
+      "github workflow",
+      "actions workflow",
+      "gh actions",
+      ".github/workflows"
+    ],
+    "content": "# GitHub Actions Guide\n\n## Critical Rules\n\n**Custom Action Deployment:**\n- New custom actions MUST be merged to the main branch before they can be used\n- After the initial merge, they should be tested from feature branches\n\n**Debug Steps:**\nAdd debug steps that print non-secret parameters when:\n- Creating a new action, OR\n- Troubleshooting a particularly tricky issue\n\n(Not required for every workflow - use when needed)\n\n## Effectiveness Principles\n\nActions cost CI minutes. Be deliberate, not iterative:\n\n1. **Monitor, don't poll** - use `gh run watch` / `gh pr checks --watch` to follow runs live\n2. **Read logs, don't guess** - fetch the failed job's log before changing code\n3. **Print actual values** - debug steps reveal the real `inputs`/`github` context, not your assumptions\n4. **Test locally first** - `act` runs workflows on your machine and avoids burning CI minutes\n5. **Plan the smallest reproduction** - one job, minimal matrix, narrow trigger before scaling up\n\nSee [README.md](README.md) for the full debugging workflow, `gh` commands, and YAML debug-step examples.\n\n## Key Gotchas\n\n1. **Secrets unavailable in fork PRs** - `pull_request` has no secrets for forks; `pull_request_target` does but **never check out or execute fork PR code inside it** (RCE with write permissions)\n2. **Pin action versions** - Use `@v4` or SHA, not `@main` (prevents breaking changes)\n3. **Explicit permissions** - Set `permissions:` block for GITHUB_TOKEN operations\n4. **Artifacts for job-to-job data** - Files don't persist between jobs without `upload-artifact`/`download-artifact`"
+  },
   {
     "name": "github-pr-review",
     "description": "Post PR review comments using the GitHub API with inline comments, suggestions, and priority labels.",
@@ -181,7 +193,7 @@ export const SKILLS_CATALOG = [
     "triggers": [
       "/github-monitor:poll"
     ],
-    "content": "# GitHub Repository Monitor\n\nCreate a cron automation that polls a single GitHub repository on a\nconfigurable schedule (default: every minute).\n\nWhen a comment on an issue or PR contains the **trigger phrase**\n(default: `@OpenHands`) it:\n\n1. Posts a GitHub comment acknowledging the request with a conversation link.\n2. Creates an OpenHands conversation pre-loaded with the issue/PR title, body,\n   labels, and recent comment history for full context.\n3. Posts a summary GitHub comment when the conversation finishes.\n\nOn every subsequent run:\n- New trigger comments on an already-tracked issue/PR are forwarded to the\n  running conversation (or re-open a previously closed one).\n- When a conversation goes idle/finished/error the agent's final response\n  is posted back as a GitHub comment.\n\n> **Local mode only.** This automation targets the local OpenHands setup\n> (`dev:automation` stack). A cloud/webhook variant is out of scope here.\n\n---\n\n## Prerequisites\n\n### Required secret\n\nVerify that the following secret is set in **OpenHands Settings → Secrets**\nbefore proceeding:\n\n| Secret name | Token type | Minimum permissions |\n|---|---|---|\n| `GITHUB_TOKEN` | Classic PAT | `repo` (private repos) or `public_repo` (public repos) |\n| `GITHUB_TOKEN` | Fine-grained PAT | Issues: Read and Write |\n\nCheck with:\n```bash\ncurl -s https://api.github.com/user \\\n  -H \"Authorization: Bearer $GITHUB_TOKEN\" \\\n  -H \"Accept: application/vnd.github+json\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))\"\n```\n\nIf the token is missing, inform the user and stop — the automation cannot\nfunction without GitHub credentials.\n\n### Optional secret\n\n| Secret name | Default | Purpose |\n|---|---|---|\n| `OPENHANDS_URL` | `http://localhost:8000` | Base URL used to build conversation links in GitHub comments |\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1  -  Verify GITHUB_TOKEN\n\nFetch the secret and run the `curl` check above.\n\n- If the secret is absent: tell the user\n  *\"GITHUB_TOKEN is not set. Please add it in OpenHands Settings → Secrets\n  (classic PAT with `repo` or `public_repo` scope, or a fine-grained PAT\n  with Issues: Read and Write).\"* Then stop.\n\n- If the API returns a non-200 or `{\"message\": \"Bad credentials\"}`:\n  tell the user the token is invalid and ask them to update it.\n\n### Step 2  -  Collect repository\n\nAsk the user: *\"Which GitHub repository should be monitored?\n(Format: `owner/repo`, e.g. `microsoft/vscode`)\"*\n\nValidate access and write permissions:\n\n```bash\ncurl -s \"https://api.github.com/repos/{owner}/{repo}\" \\\n  -H \"Authorization: Bearer $GITHUB_TOKEN\" \\\n  -H \"Accept: application/vnd.github+json\" \\\n  | python3 -c \"\nimport json, sys\nd = json.load(sys.stdin)\nif 'message' in d:\n    print('ERROR:', d['message'])\nelse:\n    perms = d.get('permissions', {})\n    print(f\\\"Accessible. Private: {d.get('private')}. Permissions: {perms}\\\")\n\"\n```\n\n- If `message: Not Found` or `message: Bad credentials` →\n  inform the user and ask them to check the repo name and token.\n- If the repo is private and `permissions.push` is `false` →\n  inform the user the token does not have write access and comments will fail.\n- If the check passes, record `REPO = \"{owner}/{repo}\"`.\n\n### Step 3  -  Collect trigger phrase\n\nAsk the user: *\"What trigger phrase should OpenHands respond to?\n(Press Enter to use the default: `@OpenHands`)\"*\n\nAccepted values: any non-empty string unlikely to appear by accident.\n\nRecord as `TRIGGER_PHRASE`. Default: `\"@openhands\"`.\n\n### Step 4  -  Collect allowed GitHub logins\n\nAsk the user: *\"Which GitHub users may trigger this automation?\nPress Enter to allow only the authenticated `GITHUB_TOKEN` owner.\nYou may also provide comma-separated GitHub logins, or `*` to allow any\nnon-bot commenter on the monitored repository.\"*\n\nMap the answer to `ALLOWED_GITHUB_LOGINS`:\n\n| User answer | `ALLOWED_GITHUB_LOGINS` value |\n|---|---|\n| Empty/default | `[\"<TOKEN_OWNER>\"]` |\n| `enyst,tofarr` | `[\"enyst\", \"tofarr\"]` |\n| `*` | `[\"*\"]` |\n\nDefault to token-owner-only unless the user explicitly chooses a broader\nallowlist. Record as `ALLOWED_GITHUB_LOGINS`.\n\n### Step 5  -  Collect event types\n\nAsk the user: *\"Which event types should be monitored?\nChoose one or more:*\n  *1. Issue and PR comments (default)*\n  *2. PR inline review comments*\n  *3. Both*\n*(Press Enter to accept the default: issue and PR comments.)\"*\n\nMap the choice to the `EVENT_TYPES` list:\n\n| Choice | `EVENT_TYPES` value |\n|---|---|\n| 1 (default) | `[\"issue_comment\"]` |\n| 2 | `[\"pr_review_comment\"]` |\n| 3 | `[\"issue_comment\", \"pr_review_comment\"]` |\n\n### Step 6  -  Collect cron schedule\n\nAsk the user: *\"How often should the automation poll GitHub?\n(Press Enter for the default: every minute.\nUse a cron expression for a different interval, e.g.:\n`*/5 * * * *` = every 5 minutes,\n`0 * * * *` = every hour)\"*\n\nDefault: `* * * * *` (every minute).\n\nRecord as `CRON_SCHEDULE`.\n\n### Step 7  -  Generate the automation script\n\nRead `scripts/main.py` from this skill's directory. Apply exactly five\nconstant substitutions near the top of the file:\n\n| Placeholder | Replace with |\n|---|---|\n| `REPO = \"owner/repo\"` | `REPO = \"{owner_repo}\"` |\n| `TRIGGER_PHRASE = \"@openhands\"` | `TRIGGER_PHRASE = \"{trigger_phrase_lower}\"` |\n| `EVENT_TYPES = [\"issue_comment\"]` | `EVENT_TYPES = {event_types_list}` |\n| `ALLOWED_GITHUB_LOGINS = [\"<TOKEN_OWNER>\"]` | `ALLOWED_GITHUB_LOGINS = {allowed_logins_list}` |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | `DEFAULT_OPENHANDS_URL = \"{url}\"` (keep default if the user has no preference) |\n\nWrite the customised script to a temporary build directory:\n```bash\nmkdir -p /tmp/github-monitor-build\n# (write the customised main.py to /tmp/github-monitor-build/main.py)\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/github-monitor-build/main.py && echo \"Syntax OK\"\n```\n\nFix any syntax errors before proceeding.\n\n### Step 8  -  Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`\n- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\nIf no Automation backend is listed in `<RUNTIME_SERVICES>`, stop and tell\nthe user to start the full automation stack.\n\n```bash\ntar -czf /tmp/github-monitor.tar.gz -C /tmp/github-monitor-build .\n\n# OPENHANDS_HOST: read from <RUNTIME_SERVICES> Automation backend url_from_agent\nOPENHANDS_HOST=\"<automation-url-from-runtime-services>\"\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-repo-monitor\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/github-monitor.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\n### Step 9  -  Create the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"GitHub Monitor: {owner}/{repo}\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"{cron_schedule}\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 55\n  }\" | python3 -m json.tool\n```\n\nRecord the returned `id`.\n\n### Step 10  -  Confirm\n\nTell the user:\n\n> ✅ **GitHub Repository Monitor** is running!\n>\n> - Automation ID: `{id}`\n> - Repository: `{owner}/{repo}`\n> - Trigger phrase: `{phrase}`\n> - Event types: `{event_types}`\n> - Allowed GitHub logins: `{allowed_logins}`\n> - Polling schedule: `{cron_schedule}`\n> - State file: `~/.openhands/workspaces/automation-state/github_poller_{id}.json`\n>\n> From an allowed GitHub login, post a comment containing `{phrase}` on any\n> issue or PR in `{owner}/{repo}` to test it. OpenHands will acknowledge with\n> a comment and a link to the new conversation.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which:\n\n1. **Loads state** from the JSON file (see `references/state-schema.md`).\n2. **Resolves and validates GITHUB_TOKEN** — aborts immediately if absent or invalid.\n3. **Polls for new events** since the previous `last_poll` timestamp:\n   - `GET /repos/{owner}/{repo}/issues/comments?since=…` for `issue_comment`\n   - `GET /repos/{owner}/{repo}/pulls/comments?since=…` for `pr_review_comment`\n4. **Processes matching comments** in chronological order:\n   - Skips bot accounts (login ending in `[bot]`) to avoid feedback loops.\n   - Skips already-processed comment IDs.\n   - Skips comments from logins outside `ALLOWED_GITHUB_LOGINS`.\n   - Checks body for the trigger phrase (case-insensitive).\n   - Extracts the issue/PR number from the comment URL.\n5. **For each trigger comment**, per issue/PR:\n   - **Active conversation** → forwards the new comment directly.\n   - **Closed conversation** → tries to re-open it; falls back to creating\n     a new conversation if the old one is unreachable.\n   - **No conversation** → fetches full context (title, body, labels, last\n     10 comments) and creates a new conversation with a detailed prompt.\n   - Posts a GitHub comment: *\"🤖 OpenHands is on it! View progress: {url}\"*\n6. **Checks active conversations** for completion:\n   - If `status ∈ {idle, finished, error, stuck}` and enough time has passed\n     since creation (debounce), fetches the agent's final response and posts\n     it as a GitHub comment. Marks the conversation `closed`.\n7. **Saves state** and fires the completion callback.\n\n---\n\n## Additional Resources\n\n### Reference Files\n\n- **`references/state-schema.md`**  -  State JSON schema, field definitions,\n  and conversation lifecycle diagram.\n- **`references/github-api.md`**  -  GitHub API endpoint reference, token\n  scopes, rate limits, and common error codes.\n\n### Script Template\n\n- **`scripts/main.py`**  -  The complete automation script. Customise the four\n  constants at the top (`REPO`, `TRIGGER_PHRASE`, `EVENT_TYPES`,\n  `DEFAULT_OPENHANDS_URL`) before packaging.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot doesn't respond to comments | `GITHUB_TOKEN` missing or wrong scopes | Verify token with `curl /user`; check scopes in Step 1 |\n| \"Bad credentials\" in run logs | Token expired | Rotate token and update the secret in Settings |\n| 404 on repo access | Repo name wrong or token has no access | Re-check `owner/repo` spelling; add token as collaborator |\n| Comments posted but no conversation created | Agent server URL wrong | Check `OPENHANDS_URL` secret and `AGENT_SERVER_URL` env var |\n| Same comment processed twice | `processed_comment_ids` cleared | State file was deleted; harmless but duplicate comment may appear |\n| Summary never posted | Conversation stuck in `running` | Open the conversation in the OpenHands UI; agent may need input |\n| No events detected after first run | `last_poll` in the future | Delete the state file to reset; it will be recreated on next run |"
+    "content": "# GitHub Repository Monitor\n\nCreate a cron automation that polls a single GitHub repository on a\nconfigurable schedule (default: every minute).\n\nWhen a comment on an issue or PR contains the **trigger phrase**\n(default: `@OpenHands`) it:\n\n1. Posts a GitHub comment acknowledging the request with a conversation link.\n2. Creates an OpenHands conversation pre-loaded with the issue/PR title, body,\n   labels, and recent comment history for full context.\n3. Posts a summary GitHub comment when the conversation finishes.\n\nOn every subsequent run:\n- New trigger comments on an already-tracked issue/PR are forwarded to the\n  running conversation (or re-open a previously closed one).\n- When a conversation goes idle/finished/error the agent's final response\n  is posted back as a GitHub comment.\n\n> **Local mode only.** This automation targets the local OpenHands setup\n> (`dev:automation` stack). A cloud/webhook variant is out of scope here.\n\n---\n\n## Prerequisites\n\n### Required secret\n\nVerify that the following secret is set in **OpenHands Settings → Secrets**\nbefore proceeding:\n\n| Secret name | Token type | Minimum permissions |\n|---|---|---|\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` (private repos) or `public_repo` (public repos) |\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Issues: Read and Write |\n\nCheck with:\n```bash\ncurl -s https://api.github.com/user \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  -H \"Accept: application/vnd.github+json\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))\"\n```\n\nIf the token is missing, inform the user and stop — the automation cannot\nfunction without GitHub credentials.\n\n### Optional secret\n\n| Secret name | Default | Purpose |\n|---|---|---|\n| `OPENHANDS_URL` | `http://localhost:8000` | Base URL used to build conversation links in GitHub comments |\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1  -  Verify GITHUB_PERSONAL_ACCESS_TOKEN\n\nFetch the secret and run the `curl` check above.\n\n- If the secret is absent: tell the user\n  *\"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in OpenHands Settings → Secrets\n  (classic PAT with `repo` or `public_repo` scope, or a fine-grained PAT\n  with Issues: Read and Write).\"* Then stop.\n\n- If the API returns a non-200 or `{\"message\": \"Bad credentials\"}`:\n  tell the user the token is invalid and ask them to update it.\n\n### Step 2  -  Collect repository\n\nAsk the user: *\"Which GitHub repository should be monitored?\n(Format: `owner/repo`, e.g. `microsoft/vscode`)\"*\n\nValidate access and write permissions:\n\n```bash\ncurl -s \"https://api.github.com/repos/{owner}/{repo}\" \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  -H \"Accept: application/vnd.github+json\" \\\n  | python3 -c \"\nimport json, sys\nd = json.load(sys.stdin)\nif 'message' in d:\n    print('ERROR:', d['message'])\nelse:\n    perms = d.get('permissions', {})\n    print(f\\\"Accessible. Private: {d.get('private')}. Permissions: {perms}\\\")\n\"\n```\n\n- If `message: Not Found` or `message: Bad credentials` →\n  inform the user and ask them to check the repo name and token.\n- If the repo is private and `permissions.push` is `false` →\n  inform the user the token does not have write access and comments will fail.\n- If the check passes, record `REPO = \"{owner}/{repo}\"`.\n\n### Step 3  -  Collect trigger phrase\n\nAsk the user: *\"What trigger phrase should OpenHands respond to?\n(Press Enter to use the default: `@OpenHands`)\"*\n\nAccepted values: any non-empty string unlikely to appear by accident.\n\nRecord as `TRIGGER_PHRASE`. Default: `\"@openhands\"`.\n\n### Step 4  -  Collect allowed GitHub logins\n\nAsk the user: *\"Which GitHub users may trigger this automation?\nPress Enter to allow only the authenticated `GITHUB_PERSONAL_ACCESS_TOKEN` owner.\nYou may also provide comma-separated GitHub logins, or `*` to allow any\nnon-bot commenter on the monitored repository.\"*\n\nMap the answer to `ALLOWED_GITHUB_LOGINS`:\n\n| User answer | `ALLOWED_GITHUB_LOGINS` value |\n|---|---|\n| Empty/default | `[\"<TOKEN_OWNER>\"]` |\n| `enyst,tofarr` | `[\"enyst\", \"tofarr\"]` |\n| `*` | `[\"*\"]` |\n\nDefault to token-owner-only unless the user explicitly chooses a broader\nallowlist. Record as `ALLOWED_GITHUB_LOGINS`.\n\n### Step 5  -  Collect event types\n\nAsk the user: *\"Which event types should be monitored?\nChoose one or more:*\n  *1. Issue and PR comments (default)*\n  *2. PR inline review comments*\n  *3. Both*\n*(Press Enter to accept the default: issue and PR comments.)\"*\n\nMap the choice to the `EVENT_TYPES` list:\n\n| Choice | `EVENT_TYPES` value |\n|---|---|\n| 1 (default) | `[\"issue_comment\"]` |\n| 2 | `[\"pr_review_comment\"]` |\n| 3 | `[\"issue_comment\", \"pr_review_comment\"]` |\n\n### Step 6  -  Collect cron schedule\n\nAsk the user: *\"How often should the automation poll GitHub?\n(Press Enter for the default: every minute.\nUse a cron expression for a different interval, e.g.:\n`*/5 * * * *` = every 5 minutes,\n`0 * * * *` = every hour)\"*\n\nDefault: `* * * * *` (every minute).\n\nRecord as `CRON_SCHEDULE`.\n\n### Step 7  -  Generate the automation script\n\nRead `scripts/main.py` from this skill's directory. Apply exactly five\nconstant substitutions near the top of the file:\n\n| Placeholder | Replace with |\n|---|---|\n| `REPO = \"owner/repo\"` | `REPO = \"{owner_repo}\"` |\n| `TRIGGER_PHRASE = \"@openhands\"` | `TRIGGER_PHRASE = \"{trigger_phrase_lower}\"` |\n| `EVENT_TYPES = [\"issue_comment\"]` | `EVENT_TYPES = {event_types_list}` |\n| `ALLOWED_GITHUB_LOGINS = [\"<TOKEN_OWNER>\"]` | `ALLOWED_GITHUB_LOGINS = {allowed_logins_list}` |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | `DEFAULT_OPENHANDS_URL = \"{url}\"` (keep default if the user has no preference) |\n\nWrite the customised script to a temporary build directory:\n```bash\nmkdir -p /tmp/github-monitor-build\n# (write the customised main.py to /tmp/github-monitor-build/main.py)\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/github-monitor-build/main.py && echo \"Syntax OK\"\n```\n\nFix any syntax errors before proceeding.\n\n### Step 8  -  Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`\n- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\nIf no Automation backend is listed in `<RUNTIME_SERVICES>`, stop and tell\nthe user to start the full automation stack.\n\n```bash\ntar -czf /tmp/github-monitor.tar.gz -C /tmp/github-monitor-build .\n\n# OPENHANDS_HOST: read from <RUNTIME_SERVICES> Automation backend url_from_agent\nOPENHANDS_HOST=\"<automation-url-from-runtime-services>\"\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-repo-monitor\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/github-monitor.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\n### Step 9  -  Create the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"GitHub Monitor: {owner}/{repo}\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"{cron_schedule}\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 55\n  }\" | python3 -m json.tool\n```\n\nRecord the returned `id`.\n\n### Step 10  -  Confirm\n\nTell the user:\n\n> ✅ **GitHub Repository Monitor** is running!\n>\n> - Automation ID: `{id}`\n> - Repository: `{owner}/{repo}`\n> - Trigger phrase: `{phrase}`\n> - Event types: `{event_types}`\n> - Allowed GitHub logins: `{allowed_logins}`\n> - Polling schedule: `{cron_schedule}`\n> - State file: `~/.openhands/workspaces/automation-state/github_poller_{id}.json`\n>\n> From an allowed GitHub login, post a comment containing `{phrase}` on any\n> issue or PR in `{owner}/{repo}` to test it. OpenHands will acknowledge with\n> a comment and a link to the new conversation.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which:\n\n1. **Loads state** from the JSON file (see `references/state-schema.md`).\n2. **Resolves and validates GITHUB_PERSONAL_ACCESS_TOKEN** — aborts immediately if absent or invalid.\n3. **Polls for new events** since the previous `last_poll` timestamp:\n   - `GET /repos/{owner}/{repo}/issues/comments?since=…` for `issue_comment`\n   - `GET /repos/{owner}/{repo}/pulls/comments?since=…` for `pr_review_comment`\n4. **Processes matching comments** in chronological order:\n   - Skips bot accounts (login ending in `[bot]`) to avoid feedback loops.\n   - Skips already-processed comment IDs.\n   - Skips comments from logins outside `ALLOWED_GITHUB_LOGINS`.\n   - Checks body for the trigger phrase (case-insensitive).\n   - Extracts the issue/PR number from the comment URL.\n5. **For each trigger comment**, per issue/PR:\n   - **Active conversation** → forwards the new comment directly.\n   - **Closed conversation** → tries to re-open it; falls back to creating\n     a new conversation if the old one is unreachable.\n   - **No conversation** → fetches full context (title, body, labels, last\n     10 comments) and creates a new conversation with a detailed prompt.\n   - Posts a GitHub comment: *\"🤖 OpenHands is on it! View progress: {url}\"*\n6. **Checks active conversations** for completion:\n   - If `status ∈ {idle, finished, error, stuck}` and enough time has passed\n     since creation (debounce), fetches the agent's final response and posts\n     it as a GitHub comment. Marks the conversation `closed`.\n7. **Saves state** and fires the completion callback.\n\n---\n\n## Additional Resources\n\n### Reference Files\n\n- **`references/state-schema.md`**  -  State JSON schema, field definitions,\n  and conversation lifecycle diagram.\n- **`references/github-api.md`**  -  GitHub API endpoint reference, token\n  scopes, rate limits, and common error codes.\n\n### Script Template\n\n- **`scripts/main.py`**  -  The complete automation script. Customise the four\n  constants at the top (`REPO`, `TRIGGER_PHRASE`, `EVENT_TYPES`,\n  `DEFAULT_OPENHANDS_URL`) before packaging.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot doesn't respond to comments | `GITHUB_PERSONAL_ACCESS_TOKEN` missing or wrong scopes | Verify token with `curl /user`; check scopes in Step 1 |\n| \"Bad credentials\" in run logs | Token expired | Rotate token and update the secret in Settings |\n| 404 on repo access | Repo name wrong or token has no access | Re-check `owner/repo` spelling; add token as collaborator |\n| Comments posted but no conversation created | Agent server URL wrong | Check `OPENHANDS_URL` secret and `AGENT_SERVER_URL` env var |\n| Same comment processed twice | `processed_comment_ids` cleared | State file was deleted; harmless but duplicate comment may appear |\n| Summary never posted | Conversation stuck in `running` | Open the conversation in the OpenHands UI; agent may need input |\n| No events detected after first run | `last_poll` in the future | Delete the state file to reset; it will be recreated on next run |"
   },
   {
     "name": "gitlab",
@@ -386,7 +398,7 @@ export const SKILLS_CATALOG = [
     "triggers": [
       "/slack-monitor:poll"
     ],
-    "content": "# Slack Channel Monitor\n\nCreate a cron automation that polls up to 10 Slack channels every minute.\nWhen a message containing the **trigger phrase** (default: `@openhands`) is\ndetected it:\n\n1. Adds a 👀 reaction to the triggering message.\n2. Opens an OpenHands conversation with the message and recent channel context.\n3. Posts a reply in the Slack thread with a link to the conversation.\n\nOn every subsequent run:\n- Replies in the thread are forwarded to the running conversation.\n- When the conversation finishes (or errors), the agent's final response is\n  posted back to the Slack thread.\n\n> **Local mode only.** This automation targets the local OpenHands setup\n> (`dev:automation` stack). A cloud/webhook-based variant is out of scope here.\n\n---\n\n## Prerequisites\n\n### Required secrets\n\nVerify that at least one of the following secrets is set in\n**OpenHands Settings → Secrets** before proceeding:\n\n| Secret name | Token type | Minimum scopes |\n|---|---|---|\n| `SLACK_BOT_TOKEN` | Bot (`xoxb-…`) | `channels:history`, `channels:read`, `reactions:write`, `chat:write` |\n| `SLACK_USER_TOKEN` | User (`xoxp-…`) | Same as bot, plus `search:read` for multi-channel efficiency |\n\nCheck with:\n```bash\n# For bot token:\ncurl -s https://slack.com/api/auth.test -H \"Authorization: Bearer $SLACK_BOT_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print('ok' if d.get('ok') else d.get('error'))\"\n\n# For user token:\ncurl -s https://slack.com/api/auth.test -H \"Authorization: Bearer $SLACK_USER_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print('ok' if d.get('ok') else d.get('error'))\"\n```\n\nIf neither token is present, inform the user and stop  -  the automation cannot\nfunction without Slack credentials.\n\n### Optional secret\n\n| Secret name | Default | Purpose |\n|---|---|---|\n| `OPENHANDS_URL` | `http://localhost:8000` | Base URL used to build conversation links posted in Slack |\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1  -  Collect channels\n\nAsk the user: *\"Which Slack channels should be monitored? You can provide\nchannel names (e.g. `#general`) or IDs (e.g. `C0123456789`).\"*\n\n**If the user provides channel names**, resolve them to IDs:\n\n```bash\nSLACK_TOKEN=\"${SLACK_BOT_TOKEN:-$SLACK_USER_TOKEN}\"\ncurl -s \"https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=200&exclude_archived=true\" \\\n  -H \"Authorization: Bearer $SLACK_TOKEN\" \\\n  | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nif not data.get('ok'):\n    print('ERROR:', data.get('error'))\n    exit(1)\nnames = set(n.lstrip('#') for n in ['CHANNEL_NAMES_HERE'.split(',')])\nfor ch in data.get('channels', []):\n    if ch['name'] in names:\n        print(f\\\"{ch['name']} → {ch['id']}\\\")\n\"\n```\n\nReplace `CHANNEL_NAMES_HERE` with the comma-separated names the user provided.\n\n**If `conversations.list` returns `missing_scope` or `not_authed`:**\nInform the user: *\"The token doesn't have permission to list channels. Please\nprovide the channel IDs directly (right-click a channel in Slack → Copy link  - \nthe last path segment starting with `C` is the ID).\"*\n\n**If the bot token lacks `channels:read`** for private channels, the user can\neither invite the bot first (`/invite @botname`) or switch to a user token.\n\nCollect up to 10 channel IDs. Record them as a Python list literal, e.g.:\n```python\n[\"C0123456789\", \"C9876543210\"]\n```\n\n### Step 2  -  Collect trigger phrase\n\nAsk the user: *\"What trigger phrase should OpenHands respond to?\n(Press Enter to use the default: `@openhands`)\"*\n\nAccepted values: any non-empty string unlikely to appear accidentally, e.g.\n`@openhands`, `jazz hands`, `take-me-to-funky-town`.\n\n### Step 3  -  Generate the automation script\n\nRead `scripts/main.py` from this skill's directory. Apply exactly three\nconstant substitutions near the top of the file:\n\n| Placeholder | Replace with |\n|---|---|\n| `TRIGGER_PHRASE = \"@openhands\"` | `TRIGGER_PHRASE = \"{user_phrase}\"` |\n| `CHANNEL_IDS: list[str] = []` | `CHANNEL_IDS: list[str] = {channel_id_list}` |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | `DEFAULT_OPENHANDS_URL = \"{url}\"` (keep default if user has no preference) |\n\nWrite the customised script to a temporary directory:\n```bash\nmkdir -p /tmp/slack-monitor-build\n# (write the customised main.py to /tmp/slack-monitor-build/main.py)\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/slack-monitor-build/main.py && echo \"Syntax OK\"\n```\n\nFix any syntax errors before proceeding.\n\n### Step 4  -  Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`\n- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\nIf no Automation backend is listed in `<RUNTIME_SERVICES>`, stop and tell\nthe user to start the full automation stack.\n\n```bash\ntar -czf /tmp/slack-monitor.tar.gz -C /tmp/slack-monitor-build .\n\n# OPENHANDS_HOST: read from <RUNTIME_SERVICES> Automation backend url_from_agent\nOPENHANDS_HOST=\"<automation-url-from-runtime-services>\"\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=slack-channel-monitor\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/slack-monitor.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\nIf the upload fails with a size error, the tarball must be under 1 MB.\n`main.py` is under 15 KB so this should never trigger.\n\n### Step 5  -  Create the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"Slack Channel Monitor\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"* * * * *\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 55\n  }\" | python3 -m json.tool\n```\n\nA 55-second timeout keeps runs well within the 60-second cron window.\n\nRecord the returned `id`  -  share it with the user as confirmation.\n\n### Step 6  -  Confirm\n\nTell the user:\n\n> ✅ **Slack Channel Monitor** is running!\n>\n> - Automation ID: `{id}`\n> - Channels: `{channel list}`\n> - Trigger phrase: `{phrase}`\n> - Polling every minute via cron `* * * * *`\n> - State file: `~/.openhands/workspaces/automation-state/slack_poller_{id}.json`\n>\n> Send a message containing `{phrase}` in any monitored channel to test it.\n> The bot will react with 👀 and reply with a link to the new conversation.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which runs **10 polling iterations** (every\n5 seconds) within the 55-second timeout window. Each iteration:\n\n1. **Loads state** from the JSON file (see `references/state-schema.md`).\n2. **Resolves the Slack token**  -  checks `SLACK_USER_TOKEN` then `SLACK_BOT_TOKEN`.\n3. **Fetches new messages:**\n   - User token + `search:read` + > 1 channel → single `search.messages` call\n     (searches for the trigger phrase across all channels).\n   - Otherwise → one `conversations.history` call per channel.\n4. **Fetches thread replies**  -  one `conversations.replies` call per tracked thread.\n5. **Processes messages** in chronological order:\n   - Skips messages already in `processed_ts` (dedup across the overlap window).\n   - Skips bot messages and any `ts` in `bot_message_ts`.\n   - Reply in a tracked thread (active **or** closed) → forwards to the existing\n     conversation; re-opens closed conversations automatically.\n   - Contains trigger phrase → 👀 reaction, create conversation, post link.\n     - Thread replies: agent receives full thread history for context.\n     - Root messages: agent receives the trigger text only.\n6. **Checks conversation statuses**  -  for each active conversation where\n   `time.time() - last_activity > 15 s`:\n   - If status is `idle`, `finished`, `error`, or `stuck` → fetch the agent's\n     final response via `/api/conversations/{id}/agent_final_response` and post\n     it to the Slack thread. Mark conversation `closed`.\n7. **Advances `last_poll`** to `now - 10 s` (overlap window prevents boundary\n   races). If a conversation creation failed, pins `last_poll` further back to\n   retry on the next iteration.\n8. **Saves state** (including `processed_ts`) and continues to the next iteration.\n9. After all iterations, fires the completion callback.\n\nDebug output is written to both stdout and a persistent log at:\n```\n{WORKSPACE_BASE_ROOT}/automation-state/slack_poller_debug.log\n```\n\n---\n\n## Additional Resources\n\n### Reference Files\n\n- **`references/slack-api.md`**  -  Slack token types, required scopes, API\n  endpoint reference, rate limits, and common error codes.\n- **`references/state-schema.md`**  -  State JSON schema, field definitions,\n  example file, and conversation lifecycle diagram.\n\n### Script Template\n\n- **`scripts/main.py`**  -  The complete automation script. Customise the three\n  constants at the top (`TRIGGER_PHRASE`, `CHANNEL_IDS`, `DEFAULT_OPENHANDS_URL`)\n  before packaging.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot doesn't react to messages | Token missing or bot not in channel | Verify token with `auth.test`; `/invite @botname` |\n| `not_in_channel` error in run logs | Bot token used but bot not a member | Invite bot or switch to user token |\n| `missing_scope` error | Token lacks required scopes | Re-install Slack app with correct scopes (see `references/slack-api.md`) |\n| No messages detected | `last_poll` timestamp is in the future | Delete the state file to reset; it will be recreated on next run |\n| Conversation link 404 | `OPENHANDS_URL` points to wrong host | Set the `OPENHANDS_URL` secret to the correct base URL |\n| Summary never posted | Conversation stuck in `running` state | Check conversation in the OpenHands UI; the agent may need intervention |\n| Duplicate conversations created | `processed_ts` state missing or corrupted | Delete the state file to reset; dedup will rebuild on next run |\n| Trigger message processed on each cron run | State file deleted between runs | Ensure `automation-state/` directory is persistent across runs |\n| Debug info needed | Need detailed per-message trace | Check `{WORKSPACE_BASE_ROOT}/automation-state/slack_poller_debug.log` |"
+    "content": "# Slack Channel Monitor\n\nCreate a cron automation that polls up to 10 Slack channels every minute.\nWhen a message containing the **trigger phrase** (default: `@openhands`) is\ndetected it:\n\n1. Adds a 👀 reaction to the triggering message.\n2. Opens an OpenHands conversation with the message and recent channel context.\n3. Posts a reply in the Slack thread with a link to the conversation.\n\nOn every subsequent run:\n- Replies in the thread are forwarded to the running conversation.\n- When the conversation finishes (or errors), the agent's final response is\n  posted back to the Slack thread.\n\n> **Local mode only.** This automation targets the local OpenHands setup\n> (`dev:automation` stack). A cloud/webhook-based variant is out of scope here.\n\n---\n\n## Prerequisites\n\n### Required secrets\n\nVerify that at least one of the following secrets is set in\n**OpenHands Settings → Secrets** before proceeding:\n\n| Secret name | Token type | Minimum scopes |\n|---|---|---|\n| `SLACK_BOT_TOKEN` | Bot (`xoxb-…`) | `channels:history`, `channels:read`, `reactions:write`, `chat:write` |\n| `SLACK_USER_TOKEN` | User (`xoxp-…`) | Same as bot, plus `search:read` for multi-channel efficiency |\n\nCheck with:\n```bash\n# For bot token:\ncurl -s https://slack.com/api/auth.test -H \"Authorization: Bearer $SLACK_BOT_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print('ok' if d.get('ok') else d.get('error'))\"\n\n# For user token:\ncurl -s https://slack.com/api/auth.test -H \"Authorization: Bearer $SLACK_USER_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print('ok' if d.get('ok') else d.get('error'))\"\n```\n\nIf neither token is present, inform the user and stop  -  the automation cannot\nfunction without Slack credentials.\n\n### Optional secret\n\n| Secret name | Default | Purpose |\n|---|---|---|\n| `OPENHANDS_URL` | `http://localhost:8000` | Base URL used to build conversation links posted in Slack |\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1  -  Collect channels\n\nAsk the user: *\"Which Slack channels should be monitored? You can provide\nchannel names (e.g. `#general`) or IDs (e.g. `C0123456789`).\"*\n\n**If the user provides channel names**, resolve them to IDs:\n\n```bash\nSLACK_TOKEN=\"${SLACK_BOT_TOKEN:-$SLACK_USER_TOKEN}\"\ncurl -s \"https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=200&exclude_archived=true\" \\\n  -H \"Authorization: Bearer $SLACK_TOKEN\" \\\n  | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nif not data.get('ok'):\n    print('ERROR:', data.get('error'))\n    exit(1)\nnames = set(n.lstrip('#') for n in ['CHANNEL_NAMES_HERE'.split(',')])\nfor ch in data.get('channels', []):\n    if ch['name'] in names:\n        print(f\\\"{ch['name']} → {ch['id']}\\\")\n\"\n```\n\nReplace `CHANNEL_NAMES_HERE` with the comma-separated names the user provided.\n\n**If `conversations.list` returns `missing_scope` or `not_authed`:**\nInform the user: *\"The token doesn't have permission to list channels. Please\nprovide the channel IDs directly (right-click a channel in Slack → Copy link  - \nthe last path segment starting with `C` is the ID).\"*\n\n**If the bot token lacks `channels:read`** for private channels, the user can\neither invite the bot first (`/invite @botname`) or switch to a user token.\n\nCollect up to 10 channel IDs. Record them as a Python list literal, e.g.:\n```python\n[\"C0123456789\", \"C9876543210\"]\n```\n\n### Step 2  -  Collect trigger phrase\n\nAsk the user: *\"What trigger phrase should OpenHands respond to?\n(Press Enter to use the default: `@openhands`)\"*\n\nAccepted values: any non-empty string unlikely to appear accidentally, e.g.\n`@openhands`, `jazz hands`, `take-me-to-funky-town`.\n\n### Step 3  -  Generate the automation script\n\nRead `scripts/main.py` from this skill's directory and **copy it verbatim**.\nApply exactly three constant substitutions near the top of the file:\n\n> **Do not reimplement, simplify, or hand-write a replacement script.**\n> The template already contains the correct secret-loading, state-path,\n> conversation-creation, and context-forwarding logic. Only the three\n> configuration constants below should change unless syntax validation fails.\n\n| Placeholder | Replace with |\n|---|---|\n| `TRIGGER_PHRASE = \"@openhands\"` | `TRIGGER_PHRASE = \"{user_phrase}\"` |\n| `CHANNEL_IDS: list[str] = []` | `CHANNEL_IDS: list[str] = {channel_id_list}` |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | `DEFAULT_OPENHANDS_URL = \"{url}\"` (keep default if user has no preference) |\n\nWrite the customised script to a temporary directory:\n```bash\nmkdir -p /tmp/slack-monitor-build\n# copy scripts/main.py to /tmp/slack-monitor-build/main.py\n# then replace only the three constants above\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/slack-monitor-build/main.py && echo \"Syntax OK\"\n```\n\nThen run a quick integrity check to confirm the template structure is still\npresent and only the configuration block was customised:\n```bash\ngrep -n 'TRIGGER_PHRASE = \"' /tmp/slack-monitor-build/main.py\ngrep -n 'CHANNEL_IDS: list\\[str\\] =' /tmp/slack-monitor-build/main.py\ngrep -n 'DEFAULT_OPENHANDS_URL = \"' /tmp/slack-monitor-build/main.py\ngrep -n 'def get_secret' /tmp/slack-monitor-build/main.py\ngrep -n 'def _state_file_path' /tmp/slack-monitor-build/main.py\ngrep -n 'def create_conversation' /tmp/slack-monitor-build/main.py\n```\n\nIf any of those checks fail, stop and re-copy the template instead of trying to\nrepair a hand-written variant.\n\n### Step 4  -  Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`\n- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\nIf no Automation backend is listed in `<RUNTIME_SERVICES>`, stop and tell\nthe user to start the full automation stack.\n\n```bash\ntar -czf /tmp/slack-monitor.tar.gz -C /tmp/slack-monitor-build .\n\n# OPENHANDS_HOST: read from <RUNTIME_SERVICES> Automation backend url_from_agent\nOPENHANDS_HOST=\"<automation-url-from-runtime-services>\"\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=slack-channel-monitor\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/slack-monitor.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\nIf the upload fails with a size error, the tarball must be under 1 MB.\n`main.py` is under 15 KB so this should never trigger.\n\n### Step 5  -  Create the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"Slack Channel Monitor\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"* * * * *\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 55\n  }\" | python3 -m json.tool\n```\n\nA 55-second timeout keeps runs well within the 60-second cron window.\n\nRecord the returned `id`  -  share it with the user as confirmation.\n\n### Step 6  -  Confirm\n\nTell the user:\n\n> ✅ **Slack Channel Monitor** is running!\n>\n> - Automation ID: `{id}`\n> - Channels: `{channel list}`\n> - Trigger phrase: `{phrase}`\n> - Polling every minute via cron `* * * * *`\n> - State file: `~/.openhands/workspaces/automation-state/slack_poller_{id}.json`\n>\n> Send a message containing `{phrase}` in any monitored channel to test it.\n> The bot will react with 👀 and reply with a link to the new conversation.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which runs **10 polling iterations** (every\n5 seconds) within the 55-second timeout window. Each iteration:\n\n1. **Loads state** from the JSON file (see `references/state-schema.md`).\n2. **Resolves the Slack token**  -  checks `SLACK_USER_TOKEN` then `SLACK_BOT_TOKEN`.\n3. **Fetches new messages:**\n   - User token + `search:read` + > 1 channel → single `search.messages` call\n     (searches for the trigger phrase across all channels).\n   - Otherwise → one `conversations.history` call per channel.\n4. **Fetches thread replies**  -  one `conversations.replies` call per tracked thread.\n5. **Processes messages** in chronological order:\n   - Skips messages already in `processed_ts` (dedup across the overlap window).\n   - Skips bot messages and any `ts` in `bot_message_ts`.\n   - Reply in a tracked thread (active **or** closed) → forwards to the existing\n     conversation; re-opens closed conversations automatically.\n   - Contains trigger phrase → 👀 reaction, create conversation, post link.\n     - Thread replies: agent receives full thread history for context.\n     - Root messages: agent receives the trigger text only.\n6. **Checks conversation statuses**  -  for each active conversation where\n   `time.time() - last_activity > 15 s`:\n   - If status is `idle`, `finished`, `error`, or `stuck` → fetch the agent's\n     final response via `/api/conversations/{id}/agent_final_response` and post\n     it to the Slack thread. Mark conversation `closed`.\n7. **Advances `last_poll`** to `now - 10 s` (overlap window prevents boundary\n   races). If a conversation creation failed, pins `last_poll` further back to\n   retry on the next iteration.\n8. **Saves state** (including `processed_ts`) and continues to the next iteration.\n9. After all iterations, fires the completion callback.\n\nDebug output is written to both stdout and a persistent log at:\n```\n{WORKSPACE_BASE_ROOT}/automation-state/slack_poller_debug.log\n```\n\n---\n\n## Additional Resources\n\n### Reference Files\n\n- **`references/slack-api.md`**  -  Slack token types, required scopes, API\n  endpoint reference, rate limits, and common error codes.\n- **`references/state-schema.md`**  -  State JSON schema, field definitions,\n  example file, and conversation lifecycle diagram.\n\n### Script Template\n\n- **`scripts/main.py`**  -  The complete automation script. Customise the three\n  constants at the top (`TRIGGER_PHRASE`, `CHANNEL_IDS`, `DEFAULT_OPENHANDS_URL`)\n  before packaging.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot doesn't react to messages | Token missing or bot not in channel | Verify token with `auth.test`; `/invite @botname` |\n| `not_in_channel` error in run logs | Bot token used but bot not a member | Invite bot or switch to user token |\n| `missing_scope` error | Token lacks required scopes | Re-install Slack app with correct scopes (see `references/slack-api.md`) |\n| No messages detected | `last_poll` timestamp is in the future | Delete the state file to reset; it will be recreated on next run |\n| Conversation link 404 | `OPENHANDS_URL` points to wrong host | Set the `OPENHANDS_URL` secret to the correct base URL |\n| Summary never posted | Conversation stuck in `running` state | Check conversation in the OpenHands UI; the agent may need intervention |\n| Duplicate conversations created | `processed_ts` state missing or corrupted | Delete the state file to reset; dedup will rebuild on next run |\n| Trigger message processed on each cron run | State file deleted between runs | Ensure `automation-state/` directory is persistent across runs |\n| Debug info needed | Need detailed per-message trace | Check `{WORKSPACE_BASE_ROOT}/automation-state/slack_poller_debug.log` |"
   },
   {
     "name": "slack-standup-digest",

package/skills/slack-channel-monitor/README.md

@@ -66,7 +66,8 @@ The skill will:
 1. Verify your Slack token is available
 2. Resolve channel names to IDs
 3. Confirm the trigger phrase (or use the default `@openhands`)
-4. Generate and upload a customised automation script
+4. Generate and upload a customised automation script by copying the template
+   and changing only the configuration constants
 5. Create the automation with cron schedule `* * * * *`
 
 ## How It Works

package/skills/slack-channel-monitor/SKILL.md

@@ -119,8 +119,13 @@ Accepted values: any non-empty string unlikely to appear accidentally, e.g.
 
 ### Step 3  -  Generate the automation script
 
-Read `scripts/main.py` from this skill's directory. Apply exactly three
-constant substitutions near the top of the file:
+Read `scripts/main.py` from this skill's directory and **copy it verbatim**.
+Apply exactly three constant substitutions near the top of the file:
+
+> **Do not reimplement, simplify, or hand-write a replacement script.**
+> The template already contains the correct secret-loading, state-path,
+> conversation-creation, and context-forwarding logic. Only the three
+> configuration constants below should change unless syntax validation fails.
 
 | Placeholder | Replace with |
 |---|---|
@@ -131,7 +136,8 @@ constant substitutions near the top of the file:
 Write the customised script to a temporary directory:
 ```bash
 mkdir -p /tmp/slack-monitor-build
-# (write the customised main.py to /tmp/slack-monitor-build/main.py)
+# copy scripts/main.py to /tmp/slack-monitor-build/main.py
+# then replace only the three constants above
 ```
 
 Validate syntax before packaging:
@@ -139,7 +145,19 @@ Validate syntax before packaging:
 python3 -m py_compile /tmp/slack-monitor-build/main.py && echo "Syntax OK"
 ```
 
-Fix any syntax errors before proceeding.
+Then run a quick integrity check to confirm the template structure is still
+present and only the configuration block was customised:
+```bash
+grep -n 'TRIGGER_PHRASE = "' /tmp/slack-monitor-build/main.py
+grep -n 'CHANNEL_IDS: list\[str\] =' /tmp/slack-monitor-build/main.py
+grep -n 'DEFAULT_OPENHANDS_URL = "' /tmp/slack-monitor-build/main.py
+grep -n 'def get_secret' /tmp/slack-monitor-build/main.py
+grep -n 'def _state_file_path' /tmp/slack-monitor-build/main.py
+grep -n 'def create_conversation' /tmp/slack-monitor-build/main.py
+```
+
+If any of those checks fail, stop and re-copy the template instead of trying to
+repair a hand-written variant.
 
 ### Step 4  -  Package and upload
 

package/tests/test_sync_extensions.py

@@ -198,6 +198,20 @@ class TestCollectNeededCommands:
             assert spec.path.parent.name == "commands"
             assert spec.path.suffix == ".md"
 
+    def test_colon_triggers_are_normalized_for_filenames(self, tmp_path, monkeypatch):
+        skill_dir = tmp_path / "skills" / "test-skill"
+        skill_dir.mkdir(parents=True)
+        (skill_dir / "SKILL.md").write_text(
+            "---\nname: test-skill\ndescription: Test\ntriggers:\n  - /test:command\n---\nBody\n"
+        )
+
+        monkeypatch.setattr("sync_extensions.SKILL_DIRS", [tmp_path / "skills"])
+
+        specs = collect_needed_commands()
+        assert [spec.path.relative_to(tmp_path).as_posix() for spec in specs] == [
+            "skills/test-skill/commands/test-command.md"
+        ]
+
 
 # ── load_marketplaces ────────────────────────────────────────────────