@openhands/agent-canvas 1.14.0 → 1.16.0

package/dist/node_modules/@openhands/extensions/skills/index.cjs

@@ -1,4 +1,4 @@
-require("../../../../_virtual/_rolldown/runtime.cjs");var e=[{name:`add-javadoc`,description:`Add comprehensive JavaDoc documentation to Java classes and methods. Use when documenting Java code, adding API documentation, or improving code documentation.`,triggers:[`javadoc`,`java documentation`,`document java`],content:`Add comprehensive JavaDoc documentation to all public classes and methods.
+require("../../../../_virtual/_rolldown/runtime.cjs");var e=[`automations`,`environment`,`code-hosting`,`agent-authoring`,`code-quality`,`integrations`,`writing`,`design`,`other`],t=[{name:`add-javadoc`,description:`Add comprehensive JavaDoc documentation to Java classes and methods. Use when documenting Java code, adding API documentation, or improving code documentation.`,triggers:[`javadoc`,`java documentation`,`document java`],content:`Add comprehensive JavaDoc documentation to all public classes and methods.
 
 ## Class-Level Documentation
 
@@ -21,7 +21,7 @@ For each public method:
 - Document preconditions and postconditions when relevant
 - Include code examples with \`{@code ...}\` for complex methods
 
-See [references/example.md](references/example.md) for before/after examples.`,category:`code-quality`,license:`MIT`,compatibility:`Requires Java source files`},{name:`add-skill`,description:'Add an external skill from a GitHub repository to the current workspace. Use when users want to import, install, or add a skill from a GitHub URL (e.g., `/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview` or "add the codereview skill from https://github.com/OpenHands/extensions/"). Handles fetching the skill files and placing them in .agents/skills/.',triggers:[],content:`# Add Skill
+See [references/example.md](references/example.md) for before/after examples.`,category:`code-quality`,license:`MIT`,compatibility:`Requires Java source files`},{name:`add-skill`,description:'Import an existing skill from a GitHub repository URL into the current workspace. Use only when the user provides or references a GitHub URL/repo to fetch from (e.g., `/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview` or "add the codereview skill from https://github.com/OpenHands/extensions/"). Handles fetching the skill files and placing them in .agents/skills/. This does not author new skills — to create a new skill from scratch (no source URL), use the skill-creator skill instead.',triggers:[],content:`# Add Skill
 
 Import skills from GitHub repositories into the current workspace.
 
@@ -64,7 +64,7 @@ Response: "✅ Added \`codereview\` to your workspace. The skill is now availabl
 
 - Creates \`.agents/skills/\` directory if it doesn't exist
 - Uses \`GITHUB_TOKEN\` for authentication (required for private repos)
-- Warns before overwriting existing skills with the same name`,category:`agent-authoring`},{name:`agent-canvas-environment`,description:`Work effectively inside a local Agent Canvas environment, including local agent-server auth, frontend/backend port discovery, safe workspace hygiene, and delegating work to a new local conversation through POST /api/conversations.`,triggers:[`agent canvas`,`agent-canvas`,`local conversation`,`delegate local conversation`,`session api key`,`X-Session-API-Key`,`localhost:8001`],content:`# Agent Canvas Environment
+- Warns before overwriting existing skills with the same name`,category:`agent-authoring`,defaultEnabled:!0},{name:`agent-canvas-environment`,description:`Work effectively inside a local Agent Canvas environment, including local agent-server auth, frontend/backend port discovery, safe workspace hygiene, and delegating work to a new local conversation through POST /api/conversations.`,triggers:[`agent canvas`,`agent-canvas`,`local conversation`,`delegate local conversation`,`session api key`,`X-Session-API-Key`,`localhost:8001`],content:`# Agent Canvas Environment
 
 Use this skill when running inside or alongside a local Agent Canvas stack, especially when the user asks to inspect the local backend, create or monitor local conversations, or delegate work to another local conversation.
 
@@ -252,7 +252,7 @@ Include:
 - checks/tests to run
 - expected final report format
 
-Do not rely on the new conversation knowing anything from the current thread.`,category:`agent-authoring`},{name:`agent-creator`,description:`Create file-based sub-agents as Markdown files following the OpenHands SDK format. Guides the user through a structured interview to collect requirements, then generates a ready-to-deploy agent file. Use this skill when the user wants to create, design, or build a new sub-agent, even if they don't use the /agent-creator command.`,triggers:[`/agent-creator`],content:`# Agent Creator
+Do not rely on the new conversation knowing anything from the current thread.`,category:`agent-authoring`,defaultEnabled:!0},{name:`agent-creator`,description:`Create file-based sub-agents as Markdown files following the OpenHands SDK format. Guides the user through a structured interview to collect requirements, then generates a ready-to-deploy agent file. Use this skill when the user wants to create, design, or build a new sub-agent, even if they don't use the /agent-creator command.`,triggers:[`/agent-creator`],content:`# Agent Creator
 
 You are an experienced AI Product Manager and Requirements Engineer specializing in
 OpenHands file-based agents. Your goal is to guide the user through a structured
@@ -452,7 +452,7 @@ the entire file unless explicitly asked.`,category:`agent-authoring`},{name:`age
   - If you've only explored a portion of the codebase, clearly note this limitation in the repository structure documentation
   - If you don't know the essential commands for working with the repository, such as lint or typecheck, ask the user and suggest adding them to AGENTS.md for future reference (with permission)
 
-When you receive this message, please review and summarize your recent actions and observations, then present a list of valuable information that should be saved in AGENTS.md to the user.`,category:`agent-authoring`},{name:`agent-sdk-builder`,description:`Guided workflow for building custom AI agents using the OpenHands Software Agent SDK. Use when you want to create a new agent through an interactive interview process that gathers requirements and generates implementation plans.`,triggers:[`/agent-builder`],content:`# Agent Builder and Interviewer Role
+When you receive this message, please review and summarize your recent actions and observations, then present a list of valuable information that should be saved in AGENTS.md to the user.`,category:`agent-authoring`,defaultEnabled:!0},{name:`agent-sdk-builder`,description:`Guided workflow for building custom AI agents using the OpenHands Software Agent SDK. Use when you want to create a new agent through an interactive interview process that gathers requirements and generates implementation plans.`,triggers:[`/agent-builder`],content:`# Agent Builder and Interviewer Role
 
 You are an expert requirements gatherer and agent builder. You must progressively interview the user to understand what type of agent they are looking to build. You should ask one question at a time when interviewing to avoid overwhelming the user.
 
@@ -478,7 +478,7 @@ After the plan is generated, please ask the user if they are ready to generate t
 
 Additional guidelines:
 - Users can configure their LLM API Key using an environment variable named "LLM_API_KEY"
-- Unless otherwise specified, default to this model: openhands/claude-sonnet-4-5-20250929. This is configurable through the LLM_BASE_MODEL environment variable.`,category:`agent-authoring`},{name:`azure-devops`,description:`Interact with Azure DevOps repositories, pull requests, and APIs using the AZURE_DEVOPS_TOKEN environment variable. Use when working with code hosted on Azure DevOps or managing Azure DevOps resources.`,triggers:[`azure_devops`,`azure`],content:`You have access to an environment variable, \`AZURE_DEVOPS_TOKEN\`, which allows you to interact with
+- Unless otherwise specified, default to this model: openhands/claude-sonnet-4-5-20250929. This is configurable through the LLM_BASE_MODEL environment variable.`,category:`agent-authoring`,defaultEnabled:!0},{name:`azure-devops`,description:`Interact with Azure DevOps repositories, pull requests, and APIs using the AZURE_DEVOPS_TOKEN environment variable. Use when working with code hosted on Azure DevOps or managing Azure DevOps resources.`,triggers:[`azure_devops`,`azure`],content:`You have access to an environment variable, \`AZURE_DEVOPS_TOKEN\`, which allows you to interact with
 the Azure DevOps API.
 
 <IMPORTANT>
@@ -825,7 +825,7 @@ COMMUNICATION STYLE:
 - Suggest concrete, actionable improvements
 - Prioritize issues that affect real users over theoretical concerns
 
-REMEMBER: DO NOT MODIFY THE CODE. PROVIDE CRITICAL BUT CONSTRUCTIVE FEEDBACK ONLY.`,category:`code-quality`},{name:`code-simplifier`,description:`Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Analyzes recently modified code across three dimensions - code reuse, code quality, and efficiency - and provides actionable improvement suggestions. This skill should be used when the user asks to "simplify code", "refine code", "clean up code", "improve code quality", or requests a simplification review of recent changes.`,triggers:[`/simplify`],content:`# Code Simplifier
+REMEMBER: DO NOT MODIFY THE CODE. PROVIDE CRITICAL BUT CONSTRUCTIVE FEEDBACK ONLY.`,category:`code-quality`,defaultEnabled:!0},{name:`code-simplifier`,description:`Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Analyzes recently modified code across three dimensions - code reuse, code quality, and efficiency - and provides actionable improvement suggestions. This skill should be used when the user asks to "simplify code", "refine code", "clean up code", "improve code quality", or requests a simplification review of recent changes.`,triggers:[`/simplify`],content:`# Code Simplifier
 
 Analyze recently modified code and suggest refinements that improve clarity, consistency, and maintainability - without changing what the code does. The review covers three complementary aspects:
 
@@ -1207,7 +1207,7 @@ To verify Docker is working correctly, run the hello-world container:
 sudo docker run hello-world
 \`\`\`
 
-PowerShell equivalent after Docker Desktop is running: \`docker run hello-world\`.`,category:`environment`},{name:`evidence-based-citations`,description:`Back factual claims and field values with official, verifiable sources. Use when the user asks to fill fields, answer questions, or make claims that must be supported by an exact quote and an official link.`,triggers:[`evidence-based`,`cite source`,`cite sources`,`official source`,`official link`,`official links`,`official docs`,`official documentation`,`verifiable source`],content:`The user wants every field value or factual claim you produce in the current response to be backed by an official, verifiable source. Apply this skill to the response that triggered it; do not assume it stays active for the rest of the conversation unless the user clearly asks for it to.
+PowerShell equivalent after Docker Desktop is running: \`docker run hello-world\`.`,category:`environment`,defaultEnabled:!0},{name:`evidence-based-citations`,description:`Back factual claims and field values with official, verifiable sources. Use when the user asks to fill fields, answer questions, or make claims that must be supported by an exact quote and an official link.`,triggers:[`evidence-based`,`cite source`,`cite sources`,`official source`,`official link`,`official links`,`official docs`,`official documentation`,`verifiable source`],content:`The user wants every field value or factual claim you produce in the current response to be backed by an official, verifiable source. Apply this skill to the response that triggered it; do not assume it stays active for the rest of the conversation unless the user clearly asks for it to.
 
 ## Output format
 
@@ -1385,7 +1385,7 @@ gh run list --repo <OWNER>/<REPO> --branch <BRANCH> --limit 5
 
 # Rerun failed jobs
 gh run rerun <RUN_ID> --repo <OWNER>/<REPO> --failed
-\`\`\``,category:`code-hosting`},{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
+\`\`\``,category:`code-hosting`,defaultEnabled:!0},{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
 
 ## Critical Rules
 
@@ -1417,7 +1417,627 @@ See [README.md](README.md) for the full debugging workflow, \`gh\` commands, and
 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\``,category:`code-hosting`},{name:`github-pr-review`,description:`Post PR review comments using the GitHub API with inline comments, suggestions, and priority labels.`,triggers:[`/github-pr-review`],content:`# GitHub PR Review
+4. **Artifacts for job-to-job data** - Files don't persist between jobs without \`upload-artifact\`/\`download-artifact\``,category:`code-hosting`},{name:`github-agents-md-maintainer`,description:`Create an automation that keeps AGENTS.md current in one or more GitHub repositories. On a schedule - weekly by default - it clones the default branch, starts an OpenHands conversation that reads the repository and creates or updates AGENTS.md, and opens a pull request with the result.`,triggers:[`/agents-md:setup`],content:`# AGENTS.md Maintainer Automation
+
+Create a cron automation that keeps each configured repository's \`AGENTS.md\` -
+the file an agent reads first when it starts work there - matching what the
+repository actually is. It is created when missing, updated when the repository
+has moved on, and left alone when it is still accurate.
+
+The automation script is deterministic: scheduling, the once-per-week claim, the
+clone, the branch, the commit, the push, the pull request, and the clone's
+removal are all handled in Python. The LLM is invoked only to read the
+repository and write the file.
+
+A week is one unit of work per repository, so a cron that fires more often than
+intended, a retried run, or a restarted service cannot open the same pull
+request twice. **A repository whose previous pull request from this automation
+is still open is skipped**, because a second one would edit the same file and
+reviewing it would tell you nothing the first did not.
+
+---
+
+## Prerequisites
+
+### Required secret
+
+Verify that the following secret is set in **OpenHands Settings -> Secrets**:
+
+| Secret name | Token type | Minimum permissions |
+|---|---|---|
+| \`GITHUB_PERSONAL_ACCESS_TOKEN\` | Classic PAT | \`repo\` |
+| \`GITHUB_PERSONAL_ACCESS_TOKEN\` | Fine-grained PAT | Contents: **Read and write**, Metadata: Read, Pull requests: **Read and write** |
+
+Contents write is required because the branch is pushed, and pull request write
+because the pull request is opened. No issue permission is needed: this
+automation never comments on an issue.
+
+Check with:
+\`\`\`bash
+curl -s https://api.github.com/user \\
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \\
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))"
+\`\`\`
+
+If the token is missing or invalid, inform the user and stop.
+
+---
+
+## Setup Workflow
+
+Follow these steps in order.
+
+### Step 1 - Verify \`GITHUB_PERSONAL_ACCESS_TOKEN\`
+
+Run the \`curl\` check above.
+
+- If absent: *"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in
+  OpenHands Settings -> Secrets."* Stop.
+- If the API returns \`{"message": "Bad credentials"}\`: tell the user the token is
+  invalid and ask them to update it. Stop.
+
+### Step 2 - Collect repositories
+
+Ask: *"Which GitHub repositories should have their AGENTS.md maintained?
+(Format: \`owner/repo\`, e.g. \`myorg/backend\`. List several separated by commas.)"*
+
+Validate access to **each** repository, and confirm the token can push:
+\`\`\`bash
+curl -s "https://api.github.com/repos/{owner}/{repo}" \\
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \\
+  | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+if 'message' in d:
+    print('ERROR:', d['message'])
+else:
+    print(f\\"Accessible. Default branch: {d.get('default_branch')}. Push: {d.get('permissions',{}).get('push')}\\")
+"
+\`\`\`
+
+Record every accepted repository into \`REPOS = ["{owner}/{repo}", ...]\`. Each
+repository keeps its own state and its own weekly claim, so one falling behind
+never blocks another.
+
+### Step 3 - Collect the schedule
+
+Ask: *"How often should AGENTS.md be checked?
+(Press Enter for the default: every Monday at 09:00 UTC, \`0 9 * * 1\`.)"*
+
+Default: \`0 9 * * 1\`. Record as \`CRON_SCHEDULE\`, and the timezone as
+\`CRON_TIMEZONE\` (default \`UTC\`).
+
+A schedule more frequent than weekly is allowed but rarely useful: the work is
+keyed by ISO week, so extra runs inside the same week do nothing but poll.
+
+### Step 4 - Collect the pull request mode
+
+Ask: *"Should the pull requests be opened as drafts?
+  1. Draft (default) - opened as a draft, ready for a human to mark ready
+  2. Ready for review - opened as a normal pull request
+(Press Enter for Draft)"*
+
+Map the choice to \`DRAFT_PULL_REQUEST\` (\`True\` or \`False\`).
+
+### Step 5 - Collect the branch prefix
+
+Ask: *"What branch prefix should the automation use?
+(Press Enter for the default: \`openhands/agents-md\`, which produces
+\`openhands/agents-md-2026-W34\`.)"*
+
+Record as \`BRANCH_PREFIX\`. The prefix is also how the automation recognises its
+own open pull requests, so changing it later makes it stop seeing the older ones.
+
+### Step 6 - Confirm the secret scope
+
+The agent is handed \`GITHUB_PERSONAL_ACCESS_TOKEN\`, because it pushes its branch
+and opens the pull request itself. Ask: *"Beyond the GitHub token, does reading
+this repository need a secret of its own? (Press Enter for none.)"*
+
+Record the answers appended to the default, as
+\`AGENT_SECRET_NAMES = ["GITHUB_PERSONAL_ACCESS_TOKEN", "NAME", ...]\`. Keep it an
+allow-list: the conversation reads a whole repository, so the rest of the
+deployment's secrets should stay out of its reach.
+
+### Step 7 - Generate the automation script
+
+Read \`scripts/main.py\` from this skill's directory. Apply exactly four constant
+substitutions near the top of the file:
+
+> The script also reads a \`config.json\` shipped beside it, if there is one, over
+> these constants. That is how the catalog entry
+> (\`automations/catalog/github-agents-md-maintainer/\`) configures an unmodified
+> copy, since a declarative host cannot rewrite Python. This setup path
+> substitutes the constants and ships no \`config.json\`, so the two never collide.
+
+| Placeholder | Replace with |
+|---|---|
+| \`REPOS = ["owner/repo"]\` | \`REPOS = ["{owner_repo}", ...]\` - one entry per repository from Step 2 |
+| \`BRANCH_PREFIX = "openhands/agents-md"\` | \`BRANCH_PREFIX = "{branch_prefix}"\` |
+| \`DRAFT_PULL_REQUEST = True\` | \`DRAFT_PULL_REQUEST = {True or False}\` |
+| \`AGENT_SECRET_NAMES: list[str] = ["GITHUB_PERSONAL_ACCESS_TOKEN"]\` | the list from Step 6 |
+
+Use a safe string writer such as \`json.dumps(value)\` when inserting user-provided
+repository names or prefixes into Python string literals.
+
+Write the customized script to a temporary build directory and validate it:
+\`\`\`bash
+mkdir -p /tmp/agents-md-build
+# write the customized main.py to /tmp/agents-md-build/main.py
+python3 -m py_compile /tmp/agents-md-build/main.py && echo "Syntax OK"
+\`\`\`
+
+### Step 8 - Package and upload
+
+Determine the Automation backend URL and auth from the \`<RUNTIME_SERVICES>\`
+block in your system context:
+- **OPENHANDS_HOST**: the Automation backend \`url_from_agent\`
+- **Auth**: \`X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\`
+
+\`\`\`bash
+tar -czf /tmp/agents-md.tar.gz -C /tmp/agents-md-build .
+
+TARBALL_PATH=$(curl -s -X POST \\
+  "\${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-agents-md-maintainer" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/gzip" \\
+  --data-binary @/tmp/agents-md.tar.gz \\
+  | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")
+
+echo "Uploaded: $TARBALL_PATH"
+\`\`\`
+
+### Step 9 - Register the automation
+
+\`\`\`bash
+curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d "{
+    \\"name\\": \\"AGENTS.md Maintainer: {repo_summary}\\",
+    \\"trigger\\": {\\"type\\": \\"cron\\", \\"schedule\\": \\"{cron_schedule}\\", \\"timezone\\": \\"{cron_timezone}\\"},
+    \\"tarball_path\\": \\"$TARBALL_PATH\\",
+    \\"entrypoint\\": \\"python3 main.py\\",
+    \\"timeout\\": 900
+  }" | python3 -m json.tool
+\`\`\`
+
+Record the returned \`id\`.
+
+### Step 10 - Confirm
+
+Tell the user:
+
+> ✅ **AGENTS.md Maintainer** is running!
+>
+> - Automation ID: \`{id}\`
+> - Repositories: \`{owner}/{repo}\`, ... (one line each)
+> - Schedule: \`{cron_schedule}\` ({cron_timezone})
+> - Branch prefix: \`{branch_prefix}\`
+> - Pull requests: \`{draft or ready for review}\`
+> - State file per repository:
+>   \`~/.openhands/workspaces/automation-state/github_agents_md_{id}_{owner}__{repo}.json\`
+>
+> Each week it reads the repository and proposes an AGENTS.md change, or reports
+> that none is needed. While one of its pull requests is still open, it stays
+> quiet - merge or close it to get the next one.
+
+---
+
+## Runtime Behaviour (per run)
+
+Each cron run executes \`main.py\`, which loads \`config.json\` if the catalog
+shipped one, checks that \`git\` is available, resolves and validates
+\`GITHUB_PERSONAL_ACCESS_TOKEN\` once, then processes every repository in \`REPOS\`
+independently. One repository failing does not stop the others; the run fails
+only if every repository fails.
+
+For each repository:
+
+1. Loads that repository's state and reads its default branch.
+2. Computes the current ISO week, e.g. \`2026-W34\`, and stops here if that week
+   is already recorded - which is what makes extra runs inside a week harmless.
+3. Lists open pull requests whose head branch starts with the branch prefix. If
+   any exist, records the skip and moves on.
+4. Asks GitHub whether \`AGENTS.md\` exists on the default branch, which decides
+   whether the run is a create or an update, and the pull request's title.
+5. Claims the week in state **before** the slow work, so an overlapping run
+   cannot start it twice.
+6. Picks the first free branch name (\`{prefix}-{period}\`, else a numbered
+   variant), clones the default branch shallow and single-branch into
+   \`{WORKSPACE_BASE}/agents-md/{owner}__{repo}/{period}\`, and creates the branch.
+7. Starts an OpenHands conversation with that clone as its working directory,
+   and only the secrets named in \`AGENT_SECRET_NAMES\` attached.
+8. When the conversation reaches \`idle\`, \`finished\`, \`error\`, or \`stuck\`:
+   - Adopts the pull request the agent opened, if GitHub says one exists.
+   - Records the failure and opens nothing if the conversation errored.
+   - Records \`no-changes\` and opens nothing if there are no commits - the
+     expected outcome when \`AGENTS.md\` is already accurate.
+   - Otherwise commits what was left, pushes, and opens the pull request itself.
+   - Retries a failed push or pull request on the next two runs before giving up.
+9. Removes the clone once the conversation is confirmed stopped.
+
+---
+
+## Additional Resources
+
+- **\`references/state-schema.md\`** - State JSON schema and the task lifecycle.
+- **\`scripts/main.py\`** - The complete automation script.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Nothing happens for a repository | A pull request from this automation is still open | Merge or close it; the next run proposes the following one |
+| Nothing happens after a manual dispatch | The current ISO week is already recorded in state | Wait for the next week, or clear that week's entry from the state document |
+| "The token cannot push to ..." | Token lacks Contents: write | Issue a token with write access, or drop the repository from \`REPOS\` |
+| \`git is not available in the automation runtime\` | The runtime image has no git | Use a runtime image that ships git |
+| Pull request says nothing changed | The agent judged AGENTS.md accurate but still committed | Read its summary in the pull request body; tighten the prompt if it keeps making cosmetic edits |
+| Every run reports \`no-changes\` | AGENTS.md is accurate, or the agent cannot read the repository | Open the conversation from the run log and check what it saw |
+| Clones remain under \`agents-md/\` | Their conversations had not stopped yet | They are removed by a later run once the conversation is terminal |`,category:`automations`},{name:`github-issue-to-pr`,description:`Create an automation that implements GitHub issues when a configurable trigger label is applied. Polls one or more repositories deterministically, clones the default branch, starts one OpenHands conversation per label event, then commits, pushes, and opens the pull request itself.`,triggers:[`/issue-to-pr:setup`],content:`# GitHub Issue to PR Automation
+
+Create a cron automation that watches one or more GitHub repositories for issues
+with a trigger label, starts an OpenHands conversation once per label event with
+the repository's default branch already checked out, and opens a pull request
+with whatever the agent produced.
+
+The automation script is deterministic: issue discovery, label-event tracking,
+state persistence, the clone, the branch, the commit, the push, the pull request,
+the issue comments, and the clone's removal are all handled in Python. The LLM is
+invoked only to write the code.
+
+The agent is told **which** issue to implement, not what it says. It fetches the
+description, the discussion, and whatever they link to itself, so nothing in the
+prompt goes stale between dispatch and the moment the agent reads it.
+
+That needs read access, so the conversation is handed exactly one secret,
+\`GITHUB_PERSONAL_ACCESS_TOKEN\`, and no MCP servers. \`AGENT_SECRET_NAMES\` stays an
+allow-list: the rest of the deployment's secret store is not reachable from a
+conversation whose instructions came from an issue.
+
+The agent also finishes the job: it commits, pushes its branch, and opens the
+pull request, so the pull request appears when the agent stops rather than on the
+next poll. The script does not trust that it happened - when the conversation
+ends it asks GitHub whether the pull request exists, and opens it itself when it
+does not. \`origin\` still carries no credential, so every GitHub command the agent
+runs has to name \`GITHUB_PERSONAL_ACCESS_TOKEN\`; the SDK only puts a secret in the
+environment of a command that mentions it, and masks it in the output.
+
+---
+
+## Prerequisites
+
+### Required secret
+
+Verify that the following secret is set in **OpenHands Settings -> Secrets**:
+
+| Secret name | Token type | Minimum permissions |
+|---|---|---|
+| \`GITHUB_PERSONAL_ACCESS_TOKEN\` | Classic PAT | \`repo\`, plus \`workflow\` |
+| \`GITHUB_PERSONAL_ACCESS_TOKEN\` | Fine-grained PAT | Contents: **Read and write**, Metadata: Read, Issues: **Read and write**, Pull requests: **Read and write**, Workflows: **Read and write** |
+
+The workflow scope is not optional in practice. An issue asking for a CI change
+is a normal issue, and GitHub rejects the whole push when a token without it
+touches \`.github/workflows/\`: *"refusing to allow a Personal Access Token to
+create or update workflow ... without \`workflow\` scope"*. The branch is rejected
+in full, so the pull request never opens.
+
+Contents write access is required because the script pushes the branch, and pull
+request write because it opens the pull request. A read-only token will poll
+happily and then fail at the point of pushing.
+
+When several repositories are monitored, the token must cover all of them.
+
+Check with:
+\`\`\`bash
+curl -s https://api.github.com/user \\
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \\
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))"
+\`\`\`
+
+If the token is missing or invalid, inform the user and stop.
+
+---
+
+## Setup Workflow
+
+Follow these steps in order.
+
+### Step 1 - Verify \`GITHUB_PERSONAL_ACCESS_TOKEN\`
+
+Run the \`curl\` check above.
+
+- If absent: *"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in
+  OpenHands Settings -> Secrets."* Stop.
+- If the API returns \`{"message": "Bad credentials"}\`: tell the user the token is
+  invalid and ask them to update it. Stop.
+
+### Step 2 - Collect repositories
+
+Ask: *"Which GitHub repositories should be watched?
+(Format: \`owner/repo\`, e.g. \`myorg/backend\`. List several separated by commas to
+serve them all from one automation.)"*
+
+Validate access to **each** repository, and confirm the token can push:
+\`\`\`bash
+curl -s "https://api.github.com/repos/{owner}/{repo}" \\
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \\
+  | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+if 'message' in d:
+    print('ERROR:', d['message'])
+else:
+    perms = d.get('permissions', {})
+    print(f\\"Accessible. Default branch: {d.get('default_branch')}. Push: {perms.get('push')}\\")
+"
+\`\`\`
+
+Record every accepted repository into \`REPOS = ["{owner}/{repo}", ...]\`. If one
+repository fails the check, say which and ask whether to continue without it. If
+\`Push: False\`, say that the automation cannot open pull requests there and ask
+for a token with write access.
+
+Each repository is polled independently and keeps its own state, so issue numbers
+never collide between them. The trigger label, branch prefix, and schedule are
+shared; a repository needing different settings wants its own automation.
+
+### Step 3 - Collect trigger label
+
+Ask: *"Which issue label should trigger an implementation?
+(Press Enter for the default: \`openhands\`.)"*
+
+Record the answer as \`TRIGGER_LABEL\`. If the label does not exist yet, tell the
+user that GitHub will still record the event once the label is created and
+applied to an issue.
+
+The automation works an issue when it sees the latest matching \`labeled\` event
+for that label. To ask for another attempt later, remove and re-apply the label -
+that opens a second branch and a second pull request rather than overwriting the
+first.
+
+### Step 4 - Collect the pull request mode
+
+Ask: *"Should the pull requests be opened as drafts?
+  1. Draft (default) - opened as a draft, ready for a human to mark ready
+  2. Ready for review - opened as a normal pull request
+(Press Enter for Draft)"*
+
+Map the choice to \`DRAFT_PULL_REQUEST\` (\`True\` or \`False\`).
+
+### Step 5 - Collect the branch prefix
+
+Ask: *"What branch prefix should the automation use?
+(Press Enter for the default: \`openhands/issue\`, which produces
+\`openhands/issue-42\`.)"*
+
+Record as \`BRANCH_PREFIX\`. Keep it free of spaces and of characters git rejects
+in a ref name.
+
+### Step 6 - Collect cron schedule
+
+Ask: *"How often should the automation poll for labelled issues?
+(Press Enter for the default: every 5 minutes.
+Use a cron expression for a different interval, e.g. \`0 * * * *\` = hourly)"*
+
+Default: \`*/5 * * * *\`.
+
+Record as \`CRON_SCHEDULE\`.
+
+### Step 7 - Confirm the secret scope
+
+The agent is handed \`GITHUB_PERSONAL_ACCESS_TOKEN\`, because it reads the issue and
+its discussion itself. Ask: *"Beyond the GitHub token, does the repository's build
+need a secret of its own - a package registry token, for example? (Press Enter for
+none.)"*
+
+Record the answers appended to the default, as
+\`AGENT_SECRET_NAMES = ["GITHUB_PERSONAL_ACCESS_TOKEN", "NAME", ...]\`.
+
+Keep it an allow-list. Forwarding the whole secret store would put every
+credential in the deployment behind a prompt written by whoever opened the issue.
+If the repositories are public and you would rather the conversation held no
+credential at all, set the list to \`[]\` - the agent can still read a public issue
+unauthenticated, and private repositories then stop working.
+
+### Step 8 - Generate the automation script
+
+Read \`scripts/main.py\` from this skill's directory. Apply exactly five constant
+substitutions near the top of the file:
+
+> The script also reads a \`config.json\` shipped beside it, if there is one, over
+> these constants. That is how the catalog entry
+> (\`automations/catalog/github-issue-to-pr/\`) configures an unmodified copy,
+> since a declarative host cannot rewrite Python. This setup path substitutes the
+> constants and ships no \`config.json\`, so the two never collide.
+
+| Placeholder | Replace with |
+|---|---|
+| \`REPOS = ["owner/repo"]\` | \`REPOS = ["{owner_repo}", ...]\` - one entry per repository collected in Step 2 |
+| \`TRIGGER_LABEL = "openhands"\` | \`TRIGGER_LABEL = "{trigger_label}"\` |
+| \`BRANCH_PREFIX = "openhands/issue"\` | \`BRANCH_PREFIX = "{branch_prefix}"\` |
+| \`DRAFT_PULL_REQUEST = True\` | \`DRAFT_PULL_REQUEST = {True or False}\` |
+| \`AGENT_SECRET_NAMES: list[str] = []\` | \`AGENT_SECRET_NAMES: list[str] = ["{name}", ...]\` |
+
+Leave \`MAX_NEW_PER_RUN\` and \`DEFAULT_OPENHANDS_URL\` alone unless the user asks
+for a different cap or a non-default OpenHands URL.
+
+A repository may be given as \`owner/repo\`, as a clone URL, or as an SSH remote;
+the script normalizes each one at startup and names the value it could not read
+rather than blaming the token.
+
+Use a safe string writer such as \`json.dumps(value)\` when inserting user-provided
+repository names, labels, or prefixes into Python string literals.
+\`json.dumps(list_of_repos)\` produces the whole \`REPOS\` list safely in one step.
+
+Write the customized script to a temporary build directory:
+\`\`\`bash
+mkdir -p /tmp/issue-to-pr-build
+# write the customized main.py to /tmp/issue-to-pr-build/main.py
+\`\`\`
+
+Validate syntax before packaging:
+\`\`\`bash
+python3 -m py_compile /tmp/issue-to-pr-build/main.py && echo "Syntax OK"
+\`\`\`
+
+Fix any syntax errors before proceeding.
+
+### Step 9 - Package and upload
+
+Determine the Automation backend URL and auth from the \`<RUNTIME_SERVICES>\`
+block in your system context:
+- **OPENHANDS_HOST**: the Automation backend \`url_from_agent\`
+- **Auth**: \`X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\`
+
+\`\`\`bash
+tar -czf /tmp/issue-to-pr.tar.gz -C /tmp/issue-to-pr-build .
+
+TARBALL_PATH=$(curl -s -X POST \\
+  "\${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-issue-to-pr" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/gzip" \\
+  --data-binary @/tmp/issue-to-pr.tar.gz \\
+  | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")
+
+echo "Uploaded: $TARBALL_PATH"
+\`\`\`
+
+### Step 10 - Register the automation
+
+\`\`\`bash
+curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d "{
+    \\"name\\": \\"GitHub Issue to PR: {repo_summary} label {trigger_label}\\",
+    \\"trigger\\": {\\"type\\": \\"cron\\", \\"schedule\\": \\"{cron_schedule}\\"},
+    \\"tarball_path\\": \\"$TARBALL_PATH\\",
+    \\"entrypoint\\": \\"python3 main.py\\",
+    \\"timeout\\": 900
+  }" | python3 -m json.tool
+\`\`\`
+
+Use the single repository as \`{repo_summary}\` when there is one, and something
+like \`3 repos\` when there are several. A poll clones a repository per queued
+issue and pushes finished branches, so the timeout allows for that; a run never
+waits for an agent to finish, only for it to be started.
+
+Record the returned \`id\`.
+
+### Step 11 - Confirm
+
+Tell the user:
+
+> ✅ **GitHub Issue to PR** is running!
+>
+> - Automation ID: \`{id}\`
+> - Repositories: \`{owner}/{repo}\`, ... (one line each)
+> - Trigger label: \`{trigger_label}\`
+> - Branch prefix: \`{branch_prefix}\`
+> - Pull requests: \`{draft or ready for review}\`
+> - Polling schedule: \`{cron_schedule}\`
+> - State file per repository:
+>   \`~/.openhands/workspaces/automation-state/github_issue_to_pr_{id}_{owner}__{repo}.json\`
+>
+> Apply the \`{trigger_label}\` label to an issue to queue an implementation. Each
+> label event is processed once. To ask for another attempt, remove and re-apply
+> the label - that opens a second branch and pull request.
+>
+> The agent runs without GitHub credentials; the automation pushes the branch and
+> opens the pull request once the agent has stopped.
+
+---
+
+## Runtime Behaviour (per poll)
+
+Each cron run executes \`main.py\`, which loads \`config.json\` if the catalog
+shipped one, checks that \`git\` is available, resolves and validates
+\`GITHUB_PERSONAL_ACCESS_TOKEN\` once, then processes every repository in \`REPOS\`
+independently. One repository failing does not stop the
+others; the run fails only if every repository fails.
+
+For each repository:
+
+1. Loads that repository's state (see \`references/state-schema.md\`) and reads its
+   default branch.
+2. Lists open issues carrying \`TRIGGER_LABEL\`, newest-updated first. Pull
+   requests are dropped, so labelling a PR never queues an implementation.
+3. For each labelled issue, up to \`MAX_NEW_PER_RUN\` new ones per run:
+   - Refetches the issue so a label removed since the listing does not start work.
+   - Finds the latest matching GitHub \`labeled\` event, and skips it if that event
+     has already been tracked.
+   - Picks the first free branch name, \`{BRANCH_PREFIX}-{number}\` or a numbered
+     variant of it.
+   - Clones the default branch, shallow and single-branch, into
+     \`{WORKSPACE_BASE}/issue-to-pr/{owner}__{repo}/issue-{number}-{event_id}\`,
+     sets the commit identity, and creates the branch. \`origin\` keeps its plain
+     HTTPS URL, so the workspace holds no credential.
+   - Starts an OpenHands conversation **whose working directory is that clone**,
+     with the issue title, body, labels, and discussion in the prompt, and only
+     the secrets named in \`AGENT_SECRET_NAMES\` attached.
+   - Comments on the issue with the branch, the label event, and the conversation
+     link.
+   - Records the task with \`status: "active"\`.
+   - If the clone or the conversation cannot be created, the clone is removed and
+     nothing is recorded, so the next poll retries the label event.
+4. For each active task:
+   - Abandons a conversation that has not reached a terminal status within two
+     hours, comments on the issue, and reclaims its clone.
+   - When the conversation reaches \`idle\`, \`finished\`, \`error\`, or \`stuck\`:
+     - Adopts the pull request the agent opened, if GitHub says one exists for
+       the branch, and comments its link on the issue. Everything below is the
+       path taken when it does not.
+     - Skips the pull request if the issue was closed meanwhile.
+     - Reports the problem on the issue if the conversation ended in \`error\` or
+       \`stuck\`.
+     - Commits whatever the agent left uncommitted, on top of any commits it made
+       itself.
+     - Posts the agent's answer on the issue, and opens no pull request, when
+       there are no commits at all - that is how an agent reports an issue too
+       ambiguous to implement.
+     - Otherwise pushes the branch, opens the pull request (draft by default,
+       titled \`[#42] <issue title>\`, with the agent's summary and \`Closes #42\` in
+       the body), and comments the link on the issue.
+     - A push or pull request that fails is retried on the next two polls before
+       the task is reported as failed, so a transient GitHub error does not throw
+       the work away.
+5. Removes the clone of every finished task, but only after confirming the
+   conversation has stopped - deleting it under a running agent would remove its
+   working directory. When that cannot be confirmed the directory is left alone
+   and the next poll tries again.
+6. Saves that repository's state atomically.
+
+The completion callback fires once for the whole run.
+
+---
+
+## Additional Resources
+
+- **\`references/state-schema.md\`** - State JSON schema, field definitions, and the
+  task lifecycle.
+- **\`scripts/main.py\`** - The complete automation script. Customize the five
+  constants at the top before packaging.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Nothing is ever queued | Trigger label not present, or applied to a pull request rather than an issue | Apply the configured label to an issue |
+| "Bad credentials" in run logs | Token expired | Rotate and update \`GITHUB_PERSONAL_ACCESS_TOKEN\` |
+| "The token cannot push to ..." | Token lacks Contents: write on that repository | Issue a token with write access, or drop the repository from \`REPOS\` |
+| Push rejected: "refusing to allow a Personal Access Token to create or update workflow" | The change touches \`.github/workflows/\` and the token has no \`workflow\` scope | Add the scope to the token; the next poll retries the same branch and opens the pull request |
+| 404 on repo access | Repo name wrong or no access | Re-check the entry in \`REPOS\` and the token's permissions |
+| \`git is not available in the automation runtime\` | The runtime image has no git | Use a runtime image that ships git; the script clones, commits, and pushes with it |
+| Issue commented "did not change any code" | The agent judged the issue too ambiguous, or made no edits | Read its answer in the comment, add the missing detail to the issue, then re-apply the label |
+| Same issue not picked up again after new comments | Its label event was already processed | Remove and re-apply the trigger label |
+| Agent reports it cannot push or open a PR | By design - it has no credentials | No action; the automation pushes and opens the pull request after the agent stops |
+| A backlog of labelled issues starts slowly | \`MAX_NEW_PER_RUN\` caps how many conversations one poll starts | Wait for the next polls, or raise the cap in the script |
+| Clones remain under \`issue-to-pr/\` | Their conversations had not stopped yet | They are removed by a later poll once the conversation is terminal |`,category:`automations`},{name:`github-pr-review`,description:`Post PR review comments using the GitHub API with inline comments, suggestions, and priority labels.`,triggers:[`/github-pr-review`],content:`# GitHub PR Review
 
 Post structured code review feedback using the GitHub API with inline comments on specific lines.
 Windows PowerShell equivalents for JSON file creation, temp paths, line lookup, and fallback \`curl\` are in \`references/windows.md\`.
@@ -1596,16 +2216,23 @@ curl -X POST \\
 5. Do NOT post comments for code that is acceptable — only comment when action is needed
 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`,category:`code-hosting`},{name:`github-pr-reviewer`,description:`Create an automation that reviews GitHub pull requests when a configurable trigger label is applied. Polls GitHub deterministically, starts one OpenHands review conversation per label event, inspects full repository and PR context, and posts the final review comment back to GitHub.`,triggers:[`/pr-reviewer:setup`],content:`# GitHub PR Reviewer Automation
+8. If no issues: post a short approval message with no inline comments`,category:`code-hosting`},{name:`github-pr-reviewer`,description:`Create an automation that reviews GitHub pull requests when a configurable trigger label is applied. Polls one or more repositories deterministically, starts one OpenHands review conversation per label event with the pull request's head commit already checked out, and publishes the review to GitHub.`,triggers:[`/pr-reviewer:setup`],content:`# GitHub PR Reviewer Automation
 
-Create a cron automation that watches a GitHub repository for pull requests
-with a review trigger label, starts an OpenHands review conversation once per
-label event, and posts the AI review as a GitHub comment.
+Create a cron automation that watches one or more GitHub repositories for pull
+requests with a review trigger label, starts an OpenHands review conversation
+once per label event, and publishes the AI review to GitHub.
 Windows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in \`references/windows.md\`.
 
 The automation script is deterministic: PR discovery, label-event tracking,
-state persistence, stale-result suppression, and GitHub comment posting are
-handled in Python. The LLM is invoked only for the review itself.
+state persistence, stale-result suppression, the repository checkout, and its
+removal are all handled in Python. The LLM is invoked only for the review
+itself.
+
+The script prepares each review's workspace before the agent starts: the pull
+request's head commit is downloaded as a tarball and extracted to a directory of
+its own, which becomes the conversation's working directory. The agent is told
+not to clone, fetch, check out, or delete anything, and the script removes the
+checkout once the conversation has stopped. Nothing accumulates between runs.
 
 ---
 
@@ -1618,7 +2245,13 @@ Verify that the following secret is set in **OpenHands Settings -> Secrets**:
 | Secret name | Token type | Minimum permissions |
 |---|---|---|
 | \`GITHUB_PERSONAL_ACCESS_TOKEN\` | Classic PAT | \`repo\` for private repos or \`public_repo\` for public repos |
-| \`GITHUB_PERSONAL_ACCESS_TOKEN\` | Fine-grained PAT | Contents: Read, Metadata: Read, Pull requests: Read, Issues: Read and Write |
+| \`GITHUB_PERSONAL_ACCESS_TOKEN\` | Fine-grained PAT | Contents: Read, Metadata: Read, Pull requests: **Read and Write**, Issues: Read and Write |
+
+Pull-request **write** access is required because the agent publishes a pull
+request review, not just an issue comment. A token with only Pull requests: Read
+will poll happily and then fail at the point of publishing.
+
+When several repositories are monitored, the token must cover all of them.
 
 Check with:
 \`\`\`bash
@@ -1644,12 +2277,13 @@ Run the \`curl\` check above.
 - If the API returns \`{"message": "Bad credentials"}\`: tell the user the
   token is invalid and ask them to update it. Stop.
 
-### Step 2 - Collect repository
+### Step 2 - Collect repositories
 
-Ask: *"Which GitHub repository should be monitored?
-(Format: \`owner/repo\`, e.g. \`myorg/backend\`)"*
+Ask: *"Which GitHub repositories should be monitored?
+(Format: \`owner/repo\`, e.g. \`myorg/backend\`. List several separated by commas to
+review them all from one automation.)"*
 
-Validate access:
+Validate access to **each** repository:
 \`\`\`bash
 curl -s "https://api.github.com/repos/{owner}/{repo}" \\
   -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \\
@@ -1663,7 +2297,13 @@ else:
 "
 \`\`\`
 
-Record \`REPO = "{owner}/{repo}"\`.
+Record every accepted repository into \`REPOS = ["{owner}/{repo}", ...]\`. If one
+repository fails the check, say which and ask whether to continue without it.
+
+Each repository is polled independently and keeps its own state, so pull-request
+numbers never collide between them. The trigger label, tone, and schedule are
+shared by all of them; a repository needing different settings wants its own
+automation.
 
 ### Step 3 - Collect trigger label
 
@@ -1706,19 +2346,27 @@ Record as \`CRON_SCHEDULE\`.
 
 ### Step 6 - Generate the automation script
 
-Read \`scripts/main.py\` from this skill's directory. Apply exactly five constant
+Read \`scripts/main.py\` from this skill's directory. Apply exactly six constant
 substitutions near the top of the file:
 
+> The script also reads a \`config.json\` shipped beside it, if there is one, over
+> these constants. That is how the catalog entry
+> (\`automations/catalog/github-pr-reviewer/\`) configures an unmodified copy,
+> since a declarative host cannot rewrite Python. This setup path substitutes the
+> constants and ships no \`config.json\`, so the two never collide.
+
 | Placeholder | Replace with |
 |---|---|
-| \`REPO = "owner/repo"\` | \`REPO = "{owner_repo}"\` |
+| \`REPOS = ["owner/repo"]\` | \`REPOS = ["{owner_repo}", ...]\` - one entry per repository collected in Step 2 |
 | \`TRIGGER_LABEL = "openhands-review"\` | \`TRIGGER_LABEL = "{trigger_label}"\` |
 | \`REVIEW_TONE = "thorough"\` | \`REVIEW_TONE = "{review_tone}"\` |
 | \`REVIEW_STYLE_INSTRUCTIONS = ""\` | \`REVIEW_STYLE_INSTRUCTIONS = "{style_instructions}"\` |
+| \`REPO_REVIEW_GUIDE_PATH = ".agents/skills/custom-codereview-guide.md"\` | leave unchanged to auto-load a repo review guide at this path, or set to \`""\` to disable |
 | \`DEFAULT_OPENHANDS_URL = "http://localhost:8000"\` | leave unchanged unless the user has a preference |
 
 Use a safe string writer such as \`json.dumps(value)\` when inserting user-provided
 repository names, labels, or style instructions into Python string literals.
+\`json.dumps(list_of_repos)\` produces the whole \`REPOS\` list safely in one step.
 
 Write the customized script to a temporary build directory:
 \`\`\`bash
@@ -1760,14 +2408,19 @@ curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1" \\
   -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
   -H "Content-Type: application/json" \\
   -d "{
-    \\"name\\": \\"GitHub PR Reviewer: {owner}/{repo} label {trigger_label}\\",
+    \\"name\\": \\"GitHub PR Reviewer: {repo_summary} label {trigger_label}\\",
     \\"trigger\\": {\\"type\\": \\"cron\\", \\"schedule\\": \\"{cron_schedule}\\"},
     \\"tarball_path\\": \\"$TARBALL_PATH\\",
     \\"entrypoint\\": \\"python3 main.py\\",
-    \\"timeout\\": 300
+    \\"timeout\\": 600
   }" | python3 -m json.tool
 \`\`\`
 
+Use the single repository as \`{repo_summary}\` when there is one, and something
+like \`3 repos\` when there are several. A poll now downloads a tarball per queued
+review, so the timeout allows for that; a run never waits for a review to
+finish, only for it to be started.
+
 Record the returned \`id\`.
 
 ### Step 9 - Confirm
@@ -1777,44 +2430,67 @@ Tell the user:
 > ✅ **GitHub PR Reviewer** is running!
 >
 > - Automation ID: \`{id}\`
-> - Repository: \`{owner}/{repo}\`
+> - Repositories: \`{owner}/{repo}\`, ... (one line each)
 > - Trigger label: \`{trigger_label}\`
 > - Review tone: \`{tone}\`
 > - Polling schedule: \`{cron_schedule}\`
-> - State file: \`~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_{id}.json\`
+> - State file per repository:
+>   \`~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_{id}_{owner}__{repo}.json\`
 >
 > Apply the \`{trigger_label}\` label to a pull request to queue a review. Each
 > label event is processed once. To request another review, remove and re-apply
 > the label.
+>
+> The review is published as a pull request review on the head commit, with
+> inline comments where a finding maps to a changed line.
 
 ---
 
 ## Runtime Behaviour (per poll)
 
-Each cron run executes \`main.py\`, which:
+Each cron run executes \`main.py\`, which resolves and validates
+\`GITHUB_PERSONAL_ACCESS_TOKEN\` once, then processes every repository in \`REPOS\`
+independently. One repository failing does not stop the others; the run fails
+only if every repository fails.
+
+For each repository:
 
-1. Loads state from the JSON file (see \`references/state-schema.md\`).
-2. Resolves and validates \`GITHUB_PERSONAL_ACCESS_TOKEN\` and repository access.
+1. Loads that repository's state (see \`references/state-schema.md\`).
+2. Verifies repository access.
 3. Lists open PRs, newest-updated first.
 4. For each open PR carrying \`TRIGGER_LABEL\`:
    - Refetches current PR metadata to avoid acting on stale list data.
    - Finds the latest matching GitHub \`labeled\` issue event.
    - Skips the event if it has already been tracked.
-   - Starts an OpenHands conversation with a review prompt that includes PR
-     metadata, the exact head SHA, label event details, and instructions to
-     clone the repo, inspect PR discussion, review comments, changed files,
-     diff, and surrounding code.
+   - Downloads the PR's head commit as a tarball and extracts it to
+     \`{WORKSPACE_BASE}/repositories/{owner}__{repo}/pr-{number}-{sha12}\`. The
+     archive is checked as it is unpacked: a single root, no absolute or \`..\`
+     paths, and symlinks skipped rather than materialised.
+   - Starts an OpenHands conversation **whose working directory is that
+     checkout**, with a review prompt carrying PR metadata, the exact head SHA,
+     and label event details.
    - Posts an acknowledgement comment with the label event, head SHA, and
      conversation link.
-   - Records the label-event review in state with \`status: "active"\`.
+   - Records the review in state with \`status: "active"\` and the checkout path.
+   - If the checkout or the conversation cannot be created, the checkout is
+     removed and nothing is recorded, so the next poll retries the label event.
 5. For each active review conversation:
    - Marks it closed without posting if the PR has closed or merged.
    - Suppresses stale results if the PR head SHA changed after the review was
      queued.
    - When the conversation reaches \`idle\`, \`finished\`, \`error\`, or \`stuck\`,
-     posts the agent's final response as a GitHub comment and marks the review
-     closed.
-6. Saves state atomically and fires the completion callback.
+     asks GitHub whether a review by the token's own user exists for that head
+     SHA. If it does, the review is complete. If it does not, the agent's final
+     response is posted as a comment so the work is not lost.
+   - Abandons a conversation that has not reached a terminal status within two
+     hours, so its checkout can be reclaimed.
+6. Removes the checkout of every finished review, but only after confirming the
+   conversation has stopped - deleting it under a running agent would remove its
+   working directory. When that cannot be confirmed the directory is left alone
+   and the next poll tries again.
+7. Saves that repository's state atomically.
+
+The completion callback fires once for the whole run.
 
 ---
 
@@ -1824,6 +2500,9 @@ Each cron run executes \`main.py\`, which:
   review lifecycle diagram.
 - **\`scripts/main.py\`** - The complete automation script. Customize the five
   constants at the top before packaging.
+- **\`tests/test_main.py\`** - Unit tests for the checkout, its removal, and state
+  handling. Run them from the skill root with \`python -m pytest tests/\` after
+  editing the script.
 
 ---
 
@@ -1833,10 +2512,14 @@ Each cron run executes \`main.py\`, which:
 |---|---|---|
 | Bot never queues reviews | Trigger label not present or no matching \`labeled\` event | Apply the configured label to the PR |
 | "Bad credentials" in run logs | Token expired | Rotate and update \`GITHUB_PERSONAL_ACCESS_TOKEN\` |
-| 404 on repo access | Repo name wrong or no access | Re-check \`owner/repo\` and token permissions |
+| 404 on repo access | Repo name wrong or no access | Re-check the entry in \`REPOS\` and the token's permissions |
+| One repository is skipped, others work | That repository failed its access check | Read the \`=== owner/repo ===\` block in the run log |
 | Same PR not reviewed after new commits | Label event was already processed | Remove and re-apply the trigger label |
 | Review result never posts | Conversation still running or stuck | Open the conversation link from the acknowledgement comment |
-| Stale review suppressed | PR head SHA changed while the agent was reviewing | Re-apply the trigger label after the latest commit |`,category:`automations`},{name:`github-repo-monitor`,description:`This skill should be used when the user asks to "monitor a GitHub repository", "watch GitHub for issues or PRs", "respond to @OpenHands mentions on GitHub", "set up an OpenHands GitHub integration", "trigger OpenHands from a GitHub comment", or "poll a GitHub repo for a trigger phrase". Guides the user through creating a cron automation that polls a single repository and starts an OpenHands conversation whenever a configurable trigger phrase is detected in an issue or PR comment.`,triggers:[`/github-monitor:poll`],content:`# GitHub Repository Monitor
+| Stale review suppressed | PR head SHA changed while the agent was reviewing | Re-apply the trigger label after the latest commit |
+| Review arrives as a plain comment, not a review | Publishing failed, so the script posted the text as a fallback | Check that the token has Pull requests: Read and Write |
+| Agent reports it cannot clone the repo | Prompt asked it not to; the workspace is already the checkout | No action - the code is at the head SHA in its working directory |
+| Checkouts remain under \`repositories/\` | Their conversations had not stopped yet | They are removed by a later poll once the conversation is terminal |`,category:`automations`},{name:`github-repo-monitor`,description:`This skill should be used when the user asks to "monitor a GitHub repository", "watch GitHub for issues or PRs", "respond to @OpenHands mentions on GitHub", "set up an OpenHands GitHub integration", "trigger OpenHands from a GitHub comment", or "poll a GitHub repo for a trigger phrase". Guides the user through creating a cron automation that polls a single repository and starts an OpenHands conversation whenever a configurable trigger phrase is detected in an issue or PR comment.`,triggers:[`/github-monitor:poll`],content:`# GitHub Repository Monitor
 
 Create a cron automation that polls a single GitHub repository on a
 configurable schedule (default: every minute).
@@ -3382,7 +4065,278 @@ Tell the user:
 > - Automation ID: \`{id}\`
 > - Teams: \`{team list}\`
 > - Mode: \`{auto-apply or suggest}\`
-> - Trigger: \`{trigger description}\``,category:`automations`},{name:`notion`,description:`Create, search, and update Notion pages/databases using the Notion API. Use for documenting work, generating runbooks, and automating knowledge base updates.`,triggers:[`notion`],content:`# Notion
+> - Trigger: \`{trigger description}\``,category:`automations`},{name:`news-digest`,description:`Create an automation that reads a list of public RSS and Atom feeds on a schedule - daily by default - keeps what is new and matches the configured topics, and has an agent write a short digest of it. It needs no credentials: the feeds are public URLs and the conversation is started with no secrets and no MCP servers.`,triggers:[`/news-digest:setup`],content:`# Daily News Digest Automation
+
+Create a cron automation that turns a list of feeds into something worth
+reading: a few hundred words a day on what happened in the topics you care
+about, with a link under each item.
+
+**It connects to nothing.** There is no token to issue, no account to link, no
+OAuth screen. That makes it the automation to run first - it exercises the
+schedule, the conversation, the model and the run log end to end while nothing
+of yours is at stake, and it is useful in its own right afterwards.
+
+The script is deterministic: the schedule, the once-a-day claim, fetching,
+parsing, the freshness window, and remembering what has already been covered
+are all Python. The LLM is invoked only for the part that
+is judgement - reading the shortlist and writing something that is not just the
+headlines pasted back. **When nothing new matches, no conversation is started
+at all**, so a quiet day costs no tokens.
+
+---
+
+## Prerequisites
+
+None. That is the point.
+
+The runtime needs outbound HTTPS to the feed hosts, which it already has if it
+can reach the model. Nothing is read from **Settings -> Secrets**, and nothing
+needs to be added there.
+
+---
+
+## Setup Workflow
+
+Follow these steps in order.
+
+### Step 1 - Collect the feeds
+
+Ask: *"Which feeds should the digest read? (One RSS or Atom URL per line. Press
+Enter for a general technology set.)"*
+
+Default:
+
+\`\`\`
+https://news.ycombinator.com/rss
+https://feeds.arstechnica.com/arstechnica/index
+https://www.theverge.com/rss/index.xml
+\`\`\`
+
+Check each one before accepting it, because a URL that returns a web page
+rather than a feed is the most common setup mistake:
+
+\`\`\`bash
+curl -sSL --max-time 20 -A "OpenHands-News-Digest/1.0" "{feed_url}" \\
+  | python3 -c "
+import sys
+from xml.etree import ElementTree
+try:
+    root = ElementTree.fromstring(sys.stdin.buffer.read())
+except ElementTree.ParseError as exc:
+    print('ERROR: not valid XML:', exc); raise SystemExit
+name = root.tag.rsplit('}', 1)[-1]
+items = [e for e in root.iter() if e.tag.rsplit('}', 1)[-1] in ('item', 'entry')]
+print(f'OK: <{name}> with {len(items)} entries' if name.lower() in ('rss', 'feed', 'rdf')
+      else f'ERROR: root element is <{name}>, which is not a feed')
+"
+\`\`\`
+
+Record every accepted URL into \`FEEDS = ["...", ...]\`. A feed that fails at
+runtime is reported and skipped, so one bad URL does not cost you the digest -
+but it is better to find out now.
+
+### Step 2 - Collect the topics
+
+Ask: *"What should the digest be about? (One topic per line, or comma
+separated. Press Enter for \`artificial intelligence, open source, developer
+tools\`. Leave it blank to summarise everything the feeds carry.)"*
+
+Record as \`TOPICS\`. Two things are worth telling the user:
+
+- The agent decides which stories are about them, reading each headline and
+  excerpt. So write topics the way you would explain your interests to a
+  colleague - \`artificial intelligence\` works even though almost every headline
+  says \`AI\`, and a story about a company releasing its model weights counts as
+  \`open source\` without using the phrase.
+- An empty list means "cover whatever is most significant". That is right for a
+  handful of narrow feeds and vaguer for a firehose.
+
+### Step 3 - Collect the schedule
+
+Ask: *"When should the digest be written? (Press Enter for the default: every
+day at 08:00 UTC, \`0 8 * * *\`.)"*
+
+Default: \`0 8 * * *\`. Record as \`CRON_SCHEDULE\`, and the timezone as
+\`CRON_TIMEZONE\` (default \`UTC\`).
+
+A schedule more frequent than daily is allowed and is not wasteful: work is
+keyed by UTC date, so extra runs stop at a state read once the day is done, and
+before that they cost one HTTP request per feed and no tokens. It is a
+reasonable way to say "write the digest as soon as there is anything to write".
+
+### Step 4 - Confirm the secret scope
+
+Do **not** ask which secrets to forward. \`AGENT_SECRET_NAMES\` is empty and
+should stay empty: the conversation summarises text fetched from the open web,
+which is written by strangers, and a credential handed to it would make every
+feed on the list an instruction channel into the deployment's secret store.
+
+If the user asks for a digest posted to Slack, Notion or a repository, that is a
+different automation - it needs that integration connected, and it should be
+built from the skill for it rather than by widening this one.
+
+### Step 5 - Generate the automation script
+
+Read \`scripts/main.py\` from this skill's directory. Apply exactly two constant
+substitutions near the top of the file:
+
+> The script also reads a \`config.json\` shipped beside it, if there is one, over
+> these constants. That is how the catalog entry
+> (\`automations/catalog/news-digest/\`) configures an unmodified copy, since a
+> declarative host cannot rewrite Python. This setup path substitutes the
+> constants and ships no \`config.json\`, so the two never collide.
+
+| Placeholder | Replace with |
+|---|---|
+| \`FEEDS = [...]\` | the list from Step 1 |
+| \`TOPICS = [...]\` | the list from Step 2, or \`[]\` for no filter |
+
+\`LOOKBACK_HOURS\` (48) and \`MAX_ITEMS\` (50) are left alone unless the user asks.
+The lookback is deliberately wider than the schedule so a failed or missed run
+is recovered by the next one; the seen-list is what stops the overlap from
+repeating anything.
+
+Use a safe string writer such as \`json.dumps(value)\` when inserting
+user-provided URLs or topics into Python string literals.
+
+Write the customized script to a temporary build directory and validate it:
+
+\`\`\`bash
+mkdir -p /tmp/news-digest-build
+# write the customized main.py to /tmp/news-digest-build/main.py
+python3 -m py_compile /tmp/news-digest-build/main.py && echo "Syntax OK"
+\`\`\`
+
+### Step 6 - Package and upload
+
+Determine the Automation backend URL and auth from the \`<RUNTIME_SERVICES>\`
+block in your system context:
+- **OPENHANDS_HOST**: the Automation backend \`url_from_agent\`
+- **Auth**: \`X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\`
+
+\`\`\`bash
+tar -czf /tmp/news-digest.tar.gz -C /tmp/news-digest-build .
+
+TARBALL_PATH=$(curl -s -X POST \\
+  "\${OPENHANDS_HOST}/api/automation/v1/uploads?name=news-digest" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/gzip" \\
+  --data-binary @/tmp/news-digest.tar.gz \\
+  | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")
+
+echo "Uploaded: $TARBALL_PATH"
+\`\`\`
+
+### Step 7 - Register the automation
+
+\`\`\`bash
+curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d "{
+    \\"name\\": \\"Daily news digest\\",
+    \\"trigger\\": {\\"type\\": \\"cron\\", \\"schedule\\": \\"{cron_schedule}\\", \\"timezone\\": \\"{cron_timezone}\\"},
+    \\"tarball_path\\": \\"$TARBALL_PATH\\",
+    \\"entrypoint\\": \\"python3 main.py\\",
+    \\"timeout\\": 900
+  }" | python3 -m json.tool
+\`\`\`
+
+Record the returned \`id\`.
+
+### Step 8 - Confirm
+
+Tell the user:
+
+> ✅ **Daily news digest** is running!
+>
+> - Automation ID: \`{id}\`
+> - Feeds: \`{url}\`, ... (one line each)
+> - Topics: \`{topics}\` (or: no filter - everything the feeds carry)
+> - Schedule: \`{cron_schedule}\` ({cron_timezone})
+> - Credentials used: **none**
+> - State file: \`~/.openhands/workspaces/automation-state/news_digest_{id}.json\`
+>
+> Each day it reads the feeds and writes the digest into the run's conversation
+> and the run log. A day with nothing new produces nothing and costs nothing -
+> the day stays open, so a later run picks up news published after this one.
+
+Then offer to dispatch it once so they can read today's digest immediately:
+
+\`\`\`bash
+curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1/{id}/dispatch" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY"
+\`\`\`
+
+---
+
+## Runtime Behaviour (per run)
+
+Each cron run executes \`main.py\`, which loads \`config.json\` if the catalog
+shipped one and then:
+
+1. Loads state (the automation service's KV store, or a local JSON file when
+   the store is unavailable).
+2. Computes today's UTC date and **stops immediately if it is already
+   recorded** - no feed is fetched, so an extra run inside a finished day costs
+   one state read.
+3. Otherwise fetches every feed with a 20-second timeout and a 4 MB cap, and
+   parses RSS 2.0, RSS 1.0/RDF and Atom by local element name. A feed that
+   fails, is not XML, or is XML that is not a feed is recorded and skipped. The
+   run fails only if *every* feed fails.
+4. Selects the stories: not already covered, and published within
+   \`LOOKBACK_HOURS\` (undated stories are treated as current rather than
+   dropped). The newest \`MAX_ITEMS\` survive. Subject is deliberately not a
+   filter here.
+5. If none survive, records the check, says which stage emptied it, and
+   **leaves the day unclaimed** so a later run can try again. No conversation,
+   no tokens.
+6. Otherwise claims the day in state *before* the slow work, so an overlapping
+   run cannot write the digest twice, then starts an OpenHands conversation
+   with the stories **and the topics** in its prompt, an empty secrets payload
+   and no MCP servers, working in \`{WORKSPACE_BASE}/news-digest/{date}\`. The
+   agent decides which stories are relevant before it writes anything.
+7. When the conversation reaches \`idle\`, \`finished\`, \`error\` or \`stuck\`:
+   - reads \`digest.md\` from the working directory, falling back to the agent's
+     final message;
+   - prints the digest into the run log and keeps its opening in state;
+   - records the stories as covered **only now**, so a run that failed leaves
+     them for the next one;
+   - removes the working directory once the conversation is confirmed stopped.
+8. Prunes the task history to the last 14 days and the seen-list to 1000
+   fingerprints, both so the state document stays inside the KV store's 64 KB
+   value limit.
+
+### How a story is recognised again
+
+Two fingerprints per story: one over the feed's own identifier (\`guid\`/\`id\`),
+one over its link with the host lowercased, the fragment removed and campaign
+parameters stripped. A story counts as already covered if **either** matches.
+Both are needed - a feed whose links carry a per-fetch campaign tag is only
+recognisable by its identifier, and two publishers syndicating the same article
+agree on nothing *but* the link.
+
+---
+
+## Additional Resources
+
+- **\`references/state-schema.md\`** - State JSON schema and the task lifecycle.
+- **\`scripts/main.py\`** - The complete automation script.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Every run says "Nothing new to digest" | Nothing was published, or it was all covered already | The run log now names which of the two it was; the digest covers what the topics miss only if the feeds carry it at all |
+| The digest ignores a topic you care about | The feeds do not carry stories about it | Add a feed that does; the agent can only choose from what was fetched |
+| A feed reports "not a feed" | The URL serves a web page, not the feed | Find the real feed URL - it is usually linked from the page as \`application/rss+xml\` |
+| A feed reports an HTTP 403 | The host blocks unknown readers | Use a different feed for that source; this automation sends no credentials by design |
+| The digest is thin and full of "Headlines" | Those feeds carry titles only | Expected for Hacker News and similar; add a feed that publishes summaries, such as Ars Technica |
+| Nothing happens after a manual dispatch | Today is already recorded in state | Read the previous run's log for the digest, or clear today's entry from the state document |
+| A day was missed entirely | The run failed, or the service was down | The next run covers it: the lookback window is 48 hours and failed runs deliberately remember nothing |
+| Digest repeats a story | Two feeds identify the same article differently, and neither the guid nor the canonical link matched | Expected occasionally; the prompt asks the agent to merge duplicate coverage it can see |`,category:`automations`},{name:`notion`,description:`Create, search, and update Notion pages/databases using the Notion API. Use for documenting work, generating runbooks, and automating knowledge base updates.`,triggers:[`notion`],content:`# Notion
 
 Windows PowerShell equivalents for the repeated Notion REST \`curl\`, environment-variable, and JSON-body snippets are in \`references/windows.md\`.
 
@@ -3942,7 +4896,7 @@ This skill is aligned against the current OpenHands API docs and implementation:
 - \`OpenHands/docs/openhands/usage/api/v1.mdx\`
 - \`OpenHands/OpenHands/openhands/app_server/v1_router.py\`
 - \`OpenHands/OpenHands/openhands/app_server/app_conversation/app_conversation_router.py\`
-- \`OpenHands/OpenHands/openhands/app_server/app_conversation/app_conversation_models.py\``,category:`agent-authoring`},{name:`openhands-automation`,description:`This skill should be used when the user asks to "create an automation", "schedule a task", "set up a cron job", "webhook integration", "event-triggered automation", or mentions automations, scheduled tasks, cron scheduling, or webhook events in OpenHands Cloud.`,triggers:[`automation`,`automations`,`scheduled task`,`cron job`,`cron schedule`,`webhook`,`webhooks`,`event trigger`,`github event`,`pull request automation`,`issue automation`,`/automation:create`],content:`# OpenHands Automations
+- \`OpenHands/OpenHands/openhands/app_server/app_conversation/app_conversation_models.py\``,category:`agent-authoring`,defaultEnabled:!0},{name:`openhands-automation`,description:`This skill should be used when the user asks to "create an automation", "schedule a task", "set up a cron job", "webhook integration", "event-triggered automation", or mentions automations, scheduled tasks, cron scheduling, or webhook events in OpenHands Cloud.`,triggers:[`automation`,`automations`,`scheduled task`,`cron job`,`cron schedule`,`webhook`,`webhooks`,`event trigger`,`github event`,`pull request automation`,`issue automation`,`/automation:create`],content:`# OpenHands Automations
 
 Create and manage automations that run inside an OpenHands agent server — triggered by cron schedules or webhook events (GitHub, custom services).
 Windows PowerShell equivalents for the automation API \`curl\` examples and shell-variable conventions are in \`references/windows.md\`.
@@ -4812,7 +5766,7 @@ See \`references/security.md\` — also covers narrowing triggers and sender-lev
 - **\`references/custom-automation.md\`** — Detailed guide for custom automations: tarball uploads, code structure (SDK and no-LLM), state persistence via the KV store, environment variables, validation rules, and complete examples. Consult this whenever you need to evaluate or recommend the custom path (including for deterministic / cost-sensitive tasks per rule 0). Only *implement* a custom automation after the user agrees to that path.
 - **\`references/ab-testing.md\`** — A/B testing for plugin automations: defining variants with weights, experiment configuration, variant selection logic, observability via conversation tags, and complete examples. Consult this when a user wants to compare plugin versions or configurations.
 - **\`references/security.md\`** — Trust boundaries: untrusted content vs. verified sender, least-privilege secrets, trigger scoping, sender authorization, pre-deploy verification. Consult whenever an automation handles external input or forwards secrets to a spawned conversation.
-- **\`references/security.md\`** — Trust boundaries for automations: untrusted event content vs. verified sender, least-privilege secret scoping for spawned conversations, narrowing triggers, sender-level authorization, and verifying a script actually runs before deploying it. Consult this whenever an automation handles external/untrusted input (GitHub issues/PRs, Slack messages, any public-facing webhook) or forwards secrets to a spawned conversation.`,category:`automations`},{name:`openhands-sdk`,description:`Reference skill for the OpenHands Software Agent SDK - the Python framework for building AI agents that write software. Use when you need to build agents with the SDK, create custom tools, configure LLMs, manage conversations, delegate to sub-agents, or deploy agents locally or remotely.`,triggers:[`openhands-sdk`,`openhands sdk`,`software-agent-sdk`,`agent-sdk`,`/sdk`],content:`# OpenHands Software Agent SDK
+- **\`references/security.md\`** — Trust boundaries for automations: untrusted event content vs. verified sender, least-privilege secret scoping for spawned conversations, narrowing triggers, sender-level authorization, and verifying a script actually runs before deploying it. Consult this whenever an automation handles external/untrusted input (GitHub issues/PRs, Slack messages, any public-facing webhook) or forwards secrets to a spawned conversation.`,category:`automations`,defaultEnabled:!0},{name:`openhands-sdk`,description:`Reference skill for the OpenHands Software Agent SDK - the Python framework for building AI agents that write software. Use when you need to build agents with the SDK, create custom tools, configure LLMs, manage conversations, delegate to sub-agents, or deploy agents locally or remotely.`,triggers:[`openhands-sdk`,`openhands sdk`,`software-agent-sdk`,`agent-sdk`,`/sdk`],content:`# OpenHands Software Agent SDK
 
 All SDK documentation lives at <https://docs.openhands.dev/sdk>.
 
@@ -4995,6 +5949,9 @@ Source: [\`examples/\`](https://github.com/OpenHands/software-agent-sdk/tree/mai
 - [\`53_client_defined_tools.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/53_client_defined_tools.py)
 - [\`54_goal_completion_loop.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/54_goal_completion_loop.py)
 - [\`55_persistent_memory.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/55_persistent_memory.py)
+- [\`56_structured_output.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/56_structured_output.py)
+- [\`57_prompt_hooks\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/57_prompt_hooks)
+- [\`58_ask_oracle_tool\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/58_ask_oracle_tool)
 
 ### [\`02_remote_agent_server/\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server)
 
@@ -5035,7 +5992,7 @@ Source: [\`examples/\`](https://github.com/OpenHands/software-agent-sdk/tree/mai
 - [\`01_loading_agentskills\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/01_loading_agentskills)
 - [\`02_loading_plugins\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/02_loading_plugins)
 - [\`03_managing_installed_skills\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/03_managing_installed_skills)
-- [\`04_mixed_marketplace_skills\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills)`,category:`agent-authoring`},{name:`pdflatex`,description:`Install and use pdflatex to compile LaTeX documents into PDFs on Linux. Use when generating academic papers, research publications, or any documents written in LaTeX.`,triggers:[`pdflatex`],content:`PdfLatex is a tool that converts Latex sources into PDF. This is specifically very important for researchers, as they use it to publish their findings. It could be installed very easily using Linux terminal, though this seems an annoying task on Windows. Installation commands are given below.
+- [\`04_mixed_marketplace_skills\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills)`,category:`agent-authoring`,defaultEnabled:!0},{name:`pdflatex`,description:`Install and use pdflatex to compile LaTeX documents into PDFs on Linux. Use when generating academic papers, research publications, or any documents written in LaTeX.`,triggers:[`pdflatex`],content:`PdfLatex is a tool that converts Latex sources into PDF. This is specifically very important for researchers, as they use it to publish their findings. It could be installed very easily using Linux terminal, though this seems an annoying task on Windows. Installation commands are given below.
 
 * Install the TexLive base
 
@@ -5694,7 +6651,7 @@ You should always complete the task requested. If there are security concerns pl
 - Never expose sensitive information in error messages
 - Log security events appropriately
 - Implement proper exception handling
-- Use secure error reporting mechanisms`,category:`code-quality`},{name:`skill-creator`,description:`This skill should be used when the user wants to "create a skill", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices.`,triggers:[],content:`# Skill Creator
+- Use secure error reporting mechanisms`,category:`code-quality`},{name:`skill-creator`,description:`This skill should be used when the user wants to "add a skill", "create a skill", "make a new skill", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices. Use this (not add-skill) when authoring a new skill from scratch rather than importing one from a GitHub URL.`,triggers:[],content:`# Skill Creator
 
 This skill provides guidance for creating effective skills.
 Windows PowerShell equivalents for the Unix shell commands used in examples are in \`references/windows.md\`.
@@ -6234,7 +7191,7 @@ To create a skill:
 7. **Test**: Verify skill loads on expected triggers
 8. **Iterate**: Improve based on usage
 
-Focus on strong trigger descriptions, progressive disclosure, and imperative writing style for effective skills that load when needed and provide targeted guidance.`,category:`agent-authoring`},{name:`slack-channel-monitor`,description:`This skill should be used when the user asks to "monitor a Slack channel", "watch Slack for messages", "create a Slack bot that responds to mentions", "set up an OpenHands Slack integration", "trigger OpenHands from Slack", "respond to @openhands in Slack", or "poll Slack channels for a trigger phrase". Guides the user through creating a cron automation that watches up to 10 Slack channels and starts an OpenHands conversation whenever a configurable trigger phrase is detected.`,triggers:[`/slack-monitor:poll`],content:`# Slack Channel Monitor
+Focus on strong trigger descriptions, progressive disclosure, and imperative writing style for effective skills that load when needed and provide targeted guidance.`,category:`agent-authoring`,defaultEnabled:!0},{name:`slack-channel-monitor`,description:`This skill should be used when the user asks to "monitor a Slack channel", "watch Slack for messages", "create a Slack bot that responds to mentions", "set up an OpenHands Slack integration", "trigger OpenHands from Slack", "respond to @openhands in Slack", or "poll Slack channels for a trigger phrase". Guides the user through creating a cron automation that watches up to 10 Slack channels and starts an OpenHands conversation whenever a configurable trigger phrase is detected.`,triggers:[`/slack-monitor:poll`],content:`# Slack Channel Monitor
 
 Create a cron automation that polls up to 10 Slack channels every minute.
 Windows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in \`references/windows.md\`.
@@ -7169,7 +8126,44 @@ After a preferred theme is selected:
 4. Maintain the theme's visual identity across all slides
 
 ## Create your Own Theme
-To handle cases where none of the existing themes work for an artifact, create a custom theme. Based on provided inputs, generate a new theme similar to the ones above. Give the theme a similar name describing what the font/color combinations represent. Use any basic description provided to choose appropriate colors/fonts. After generating the theme, show it for review and verification. Following that, apply the theme as described above.`,category:`design`,license:`Complete terms in LICENSE.txt`},{name:`upstream-fork-sync`,description:`This skill should be used when the user asks to "keep a fork in sync", "rebase local changes on upstream", "sync my fork nightly", "long-lived fork", or "automate upstream rebases". Guides the user through creating a cron automation that fetches upstream changes, rebases local customizations on top, verifies the software works, and replaces the running version when the rebase is clean.`,triggers:[`/upstream-fork-sync:setup`],content:`# Upstream Fork Sync Automation
+To handle cases where none of the existing themes work for an artifact, create a custom theme. Based on provided inputs, generate a new theme similar to the ones above. Give the theme a similar name describing what the font/color combinations represent. Use any basic description provided to choose appropriate colors/fonts. After generating the theme, show it for review and verification. Following that, apply the theme as described above.`,category:`design`,license:`Complete terms in LICENSE.txt`},{name:`ticket-to-code-change`,description:`Set up a ticket-to-code-change automation using Jira or Linear as the issue tracker and GitHub, GitLab, or Bitbucket as the source-control provider. Watches for implementation-ready tickets, starts an OpenHands conversation to implement and test the request, opens a pull or merge request, and links the result back to the ticket.`,triggers:[`/ticket-to-code-change:setup`],content:`# Ticket to code change
+
+Create an automation that turns implementation-ready tickets into tested pull
+requests or merge requests.
+
+## Information to collect
+
+Ask the user for:
+
+1. The issue tracker: Jira Cloud or Linear.
+2. The source-control provider: GitHub, GitLab, or Bitbucket Cloud.
+3. The project or team to watch and the label or workflow state that means
+   "implementation ready".
+4. How a ticket identifies its target repository and base branch.
+5. The polling schedule or issue event to use.
+6. The ticket state to set when work starts and when the change request opens.
+7. Whether linked dependencies must be completed before dispatch.
+
+## Setup workflow
+
+1. Verify that both required integrations are connected and can read the
+   selected project and repository.
+2. Prefer an issue event trigger when the deployment can receive events;
+   otherwise use cron polling with durable issue-ID deduplication.
+3. Limit each run to a small configurable number of new tickets. On initial
+   deployment, establish a baseline instead of dispatching the entire backlog.
+4. Build a prompt that includes the full ticket, acceptance criteria,
+   dependency status, repository, base branch, and provider-specific request
+   terminology. Require the agent to run the repository's tests before opening
+   the pull request or merge request.
+5. Create the automation through the Automation backend described in
+   \`<RUNTIME_SERVICES>\`. Use its prompt-preset endpoint and authenticate with
+   the runtime-provided automation API key.
+6. Configure the automation to post the OpenHands conversation URL immediately
+   and the resulting pull-request or merge-request URL back to the ticket.
+
+Do not dispatch tickets with unresolved dependencies or without an unambiguous
+target repository; comment on the ticket with the missing information instead.`,category:`automations`},{name:`upstream-fork-sync`,description:`This skill should be used when the user asks to "keep a fork in sync", "rebase local changes on upstream", "sync my fork nightly", "long-lived fork", or "automate upstream rebases". Guides the user through creating a cron automation that fetches upstream changes, rebases local customizations on top, verifies the software works, and replaces the running version when the rebase is clean.`,triggers:[`/upstream-fork-sync:setup`],content:`# Upstream Fork Sync Automation
 
 Create a cron automation that keeps a long-lived fork current with its
 upstream source. On every run it fetches the latest upstream changes,
@@ -7462,5 +8456,5 @@ vercel logs <deployment-url>
 
 # Pull environment variables locally
 vercel env pull
-\`\`\``,category:`integrations`}];exports.default=e;
+\`\`\``,category:`integrations`}],n=[`add-skill`,`agent-canvas-environment`,`agent-memory`,`agent-sdk-builder`,`code-review`,`docker`,`github`,`openhands-api`,`openhands-automation`,`openhands-sdk`,`skill-creator`];exports.DEFAULT_ENABLED_SKILL_NAMES=n,exports.SKILL_CATEGORY_IDS=e,exports.default=t;
 //# sourceMappingURL=index.cjs.map