@openhands/agent-canvas 1.1.0 → 1.2.1

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

@@ -56,6 +56,8 @@ python3 scripts/fetch_skill.py "https://github.com/OpenHands/extensions/tree/mai
 ls /path/to/workspace/.agents/skills/codereview/SKILL.md
 \`\`\`
 
+On Windows, use \`python\` if \`python3\` is not available and verify with PowerShell, for example: \`Test-Path C:\\path\\to\\workspace\\.agents\\skills\\codereview\\SKILL.md\`.
+
 Response: "✅ Added \`codereview\` to your workspace. The skill is now available."
 
 ## Notes
@@ -101,12 +103,28 @@ HTTP \`200\` means the backend and key work.
 
 Use \`POST /api/conversations\` with:
 
-- current \`/api/settings\` as the base agent profile
+- the **encrypted** \`agent_settings\` from \`GET /api/settings\` (with \`X-Expose-Secrets: encrypted\`), which carries the real Fernet-encrypted \`llm.api_key\`, the existing \`agent_context\`, and the agent kind — so you never handle plaintext credentials and you don't drop the caller's skill/context config
+- \`secrets_encrypted: true\` so the agent-server decrypts that \`api_key\` server-side
+- the exec tool set merged into \`agent_settings.tools\` (and \`task_tool_set\` when you enable sub-agents)
+- \`tool_module_qualnames\` for any non-SDK tools (e.g. \`canvas_ui\`)
+- \`agent_context.load_public_skills\`/\`load_user_skills\`/\`load_project_skills\` set to \`true\` if the delegated agent should inherit bundled/user/project skills
 - a fresh absolute workspace directory
 - \`initial_message.run: true\`
 - \`worktree: false\` when the workspace is already isolated
 
-Template:
+### Credential handling — important
+
+\`GET /api/settings\` (default) **masks** every credential — \`llm.api_key\` comes back as the literal string \`"**********"\`. If you forward that verbatim, the new conversation authenticates with the placeholder and fails immediately with \`LLMAuthenticationError\` (\`You must provide an API key\`).
+
+The supported way to obtain forwardable credentials is the **\`X-Expose-Secrets: encrypted\`** request header. With it, \`/api/settings\` returns the real \`llm.api_key\` as a **Fernet-encrypted token** (starts with \`gAAAAA\`) intended to be sent back to the server with \`secrets_encrypted: true\`; the agent-server's \`decrypt_incoming_llm_secrets\` decrypts it server-side. Do **not** read \`~/.openhands/profiles/*.json\` directly — that is brittle (the caller may not share the backend's home directory, \`active_profile\` may be null, the profile store may live elsewhere).
+
+Two working approaches:
+
+1. **\`agent_profile_id\` (simplest, but no tools)** — send only \`agent_profile_id: "<uuid>"\` (from \`GET /api/agent-profiles\` → the profile whose \`id\` equals \`active_agent_profile_id\` from \`/api/settings\`). The server resolves the LLM key + agent kind from the profile. Mutually exclusive with \`agent\`/\`agent_settings\`, and the \`openhands\` agent-profile schema forbids \`tools\`/\`include_default_tools\`, so the conversation gets **zero exec tools** this way. Use only when the task needs no tools.
+
+2. **Encrypted \`agent_settings\` (full tools, preserves context)** — start from the encrypted \`/api/settings\` \`agent_settings\` payload, drop \`schema_version\` and \`mcp_config\` (to avoid MCP-connection failures at creation time), merge in the exec tool set and \`load_*_skills\` flags, and send with \`secrets_encrypted: true\`. This is the pattern for real delegated work.
+
+Template (full tools, preserves context):
 
 \`\`\`bash
 set -euo pipefail
@@ -121,26 +139,57 @@ test -n "$KEY" || { echo "No Agent Canvas session API key found" >&2; exit 1; }
 WORKDIR="\${WORKDIR:-$HOME/workspace/delegated/$(date +%Y%m%d-%H%M%S)}"
 mkdir -p "$WORKDIR"
 
-SETTINGS_JSON="$(curl -sS -H "X-Session-API-Key: $KEY" "$BASE/api/settings")"
+# Fetch the agent_settings with ENCRYPTED secrets exposed. This returns the
+# real llm.api_key as a Fernet token (gAAAAA...) plus the existing
+# agent_context/agent kind, so we preserve the caller's config and never
+# handle plaintext credentials.
+SETTINGS_JSON="$(curl -sS -H "X-Session-API-Key: $KEY" -H "X-Expose-Secrets: encrypted" "$BASE/api/settings")"
+
 PROMPT='Write a complete, task-specific prompt here. Include repo, branch, constraints, validation, and expected report.'
 
 PAYLOAD="$(jq -n --argjson settings "$SETTINGS_JSON" --arg prompt "$PROMPT" --arg workdir "$WORKDIR" '
-  def agent_settings:
+  # Start from the encrypted agent_settings so llm.api_key (Fernet token),
+  # agent_kind, and agent_context are preserved. Drop schema_version and
+  # mcp_config (MCP servers can fail to connect at creation time; the profile
+  # can be re-resolved later if needed).
+  def base_agent_settings:
     ($settings.agent_settings // {})
     | del(.schema_version)
-    | . + {
-        agent_context: ((.agent_context // {}) + {
-          load_public_skills: true,
-          load_user_skills: true,
-          load_project_skills: true
-        })
-      };
+    | del(.mcp_config);
+
+  # Merge the exec tool set into the existing tools list. Include task_tool_set
+  # when sub-agents are enabled — enable_sub_agents alone does not expose the
+  # delegation tool; Agent Canvas adds task_tool_set for that.
+  def with_tools:
+    .tools = ((.tools // []) + [
+      {name: "terminal", params: {}},
+      {name: "file_editor", params: {}},
+      {name: "task_tracker", params: {}},
+      {name: "browser_tool_set", params: {}},
+      {name: "canvas_ui", params: {}}
+    ] + (if .enable_sub_agents then [{name: "task_tool_set", params: {}}] else [] end)
+    | unique_by(.name));
+
+  # Preserve the existing agent_context and enable skill loading for the
+  # delegated agent (defaults are false, so set these explicitly).
+  def with_skill_loading:
+    .agent_context = ((.agent_context // {}) + {
+      load_public_skills: true,
+      load_user_skills: true,
+      load_project_skills: true
+    });
+
   ($settings.conversation_settings // {}) as $conv |
   {
-    agent_settings: agent_settings,
+    secrets_encrypted: true,
+    agent_settings: (base_agent_settings | with_tools | with_skill_loading),
+    tool_module_qualnames: { canvas_ui: "canvas_ui_tool" },
     workspace: {kind: "LocalWorkspace", working_dir: $workdir},
     confirmation_policy: {kind: "NeverConfirm"},
-    max_iterations: (($conv.max_iterations // 80) | if . == null then 80 else . end),
+    # Delegated tasks usually need more than the SDK default of 80 iterations;
+    # default to the caller's conversation_settings value (1000 in Agent Canvas)
+    # so long-running tasks aren't cut off prematurely. Override per-task if needed.
+    max_iterations: (($conv.max_iterations // 1000) | if . == null then 1000 else . end),
     stuck_detection: true,
     autotitle: true,
     worktree: false,
@@ -158,6 +207,20 @@ curl -sS -X POST "$BASE/api/conversations" \\
   --data-binary "$PAYLOAD" | jq '{id, title, execution_status, workspace}'
 \`\`\`
 
+Verify the new conversation actually has tools and is running (not errored):
+
+\`\`\`bash
+CID="<conversation_id>"
+curl -sS -H "X-Session-API-Key: $KEY" "$BASE/api/conversations/$CID" \\
+  | jq '{execution_status, tools: [.agent.tools[]?.name]}'
+curl -sS -H "X-Session-API-Key: $KEY" "$BASE/api/conversations/$CID/events/search?limit=20" \\
+  | jq '[.events[]? | select(.kind=="ConversationErrorEvent") | .code] // []'
+\`\`\`
+
+\`execution_status\` should be \`running\`/\`idle\`/\`finished\` (not \`error\`), \`tools\` should list the exec tools, and there should be no \`ConversationErrorEvent\`.
+
+If MCP servers configured in the profile are unreachable, conversation creation can fail with \`MCP Connection Failure\`; the template drops \`mcp_config\` from the forwarded \`agent_settings\` to avoid that.
+
 Report both links:
 
 - UI: \`http://localhost:8000/conversations/<conversation_id>\`
@@ -439,6 +502,8 @@ git remote -v && git branch # to find the current org, repo and branch
 git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
 \`\`\`
 
+On Windows PowerShell, run those \`git\` commands as separate commands if \`&&\` is not supported by the installed shell.
+
 ## Azure DevOps API Usage
 
 When working with Azure DevOps API, you need to use Basic authentication with your Personal Access Token (PAT). The username is ignored (empty string), and the password is the PAT.
@@ -452,11 +517,115 @@ AUTH=$(echo -n ":$AZURE_DEVOPS_TOKEN" | base64)
 curl -H "Authorization: Basic $AUTH" -H "Content-Type: application/json" https://dev.azure.com/{organization}/{project}/_apis/git/repositories?api-version=7.1
 \`\`\`
 
+PowerShell equivalent for the PAT header:
+
+\`\`\`powershell
+$auth = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$env:AZURE_DEVOPS_TOKEN"))
+Invoke-RestMethod \`
+  -Headers @{ Authorization = "Basic $auth"; "Content-Type" = "application/json" } \`
+  -Uri "https://dev.azure.com/{organization}/{project}/_apis/git/repositories?api-version=7.1"
+\`\`\`
+
 Common API endpoints:
 - List repositories: \`https://dev.azure.com/{organization}/{project}/_apis/git/repositories?api-version=7.1\`
 - Get repository details: \`https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}?api-version=7.1\`
 - List pull requests: \`https://dev.azure.com/{organization}/{project}/_apis/git/pullrequests?api-version=7.1\`
-- Create pull request: \`https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version=7.1\` (POST)`},{name:`bitbucket`,description:`Interact with Bitbucket repositories and pull requests using the BITBUCKET_TOKEN environment variable. Use when working with code hosted on Bitbucket or managing Bitbucket resources via API.`,triggers:[`bitbucket`,`git`],content:'You have access to an environment variable, `BITBUCKET_TOKEN`, which allows you to interact with\nthe Bitbucket API.\n\n<IMPORTANT>\nYou can use `curl` with the `BITBUCKET_TOKEN` to interact with Bitbucket\'s API.\nALWAYS use the Bitbucket API for operations instead of a web browser.\nALWAYS use the `create_bitbucket_pr` tool to open a pull request\n</IMPORTANT>\n\nOnly rewrite the Bitbucket remote if a push actually fails with authentication errors and the user has asked you to push. Do not proactively rewrite `origin`. OpenHands OSS commonly stores `BITBUCKET_TOKEN` in the same unencoded `user:token` form used by commands such as `curl --user "$BITBUCKET_TOKEN" ...`, so keep it in that form unless you truly need to embed it in a Git remote URL.\n\nIf you need a non-interactive HTTPS remote URL, split `BITBUCKET_TOKEN` on the first `:` and URL-encode each part before calling `git remote set-url`. This avoids breaking usernames or emails that contain reserved URL characters such as `@`:\n\n```bash\nBB_USER="${BITBUCKET_TOKEN%%:*}" && \\\nBB_PASS="${BITBUCKET_TOKEN#*:}" && \\\nENCODED_USER=$(python3 -c \'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))\' "$BB_USER") && \\\nENCODED_PASS=$(python3 -c \'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))\' "$BB_PASS") && \\\ngit remote set-url origin "https://${ENCODED_USER}:${ENCODED_PASS}@bitbucket.org/username/repo.git"\n```\n\nAtlassian\'s Bitbucket Cloud docs recommend avoiding long-lived credentials in the remote URL when possible. Their API token examples use either `https://{bitbucket_username}:{api_token}@...` or `https://x-bitbucket-api-token-auth:{api_token}@...`; OpenHands users should only construct those URLs on demand, with proper URL encoding.\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_bitbucket_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```'},{name:`code-review`,description:`Rigorous code review focusing on data structures, simplicity, security, pragmatism, and risk/safety evaluation. Provides brutally honest, actionable feedback on pull requests or merge requests, including a risk assessment for every review. Use when reviewing code changes.`,triggers:[`/codereview`,`/codereview-roasted`],content:`PERSONA:
+- Create pull request: \`https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/pullrequests?api-version=7.1\` (POST)`},{name:`bitbucket`,description:`Bitbucket integration hub. Detects whether the repository is on Bitbucket Cloud or Bitbucket Data Center and directs you to the matching detailed skill (bitbucket-cloud or bitbucket-data-center). Use for any Bitbucket repository or pull request task.`,triggers:[`bitbucket`,`git`],content:`You are working with **Bitbucket**, which ships as two distinct products that behave
+differently:
+
+- **Bitbucket Cloud** (\`bitbucket.org\`) — authenticates with the \`BITBUCKET_TOKEN\`
+  environment variable.
+- **Bitbucket Data Center** (self-hosted Bitbucket Server) — authenticates with the
+  \`BITBUCKET_DATA_CENTER_TOKEN\` environment variable.
+
+They use different REST APIs, repository identifiers, git remote URL formats, and pull
+request tools, so you must first determine which one you are on, then load the matching
+detailed skill for full instructions.
+
+## Step 1 — Detect which Bitbucket you are on
+
+Check which token environment variable is present. Environment variable names are
+case-sensitive, so look for it case-insensitively:
+
+\`\`\`bash
+env | grep -i 'bitbucket' || echo "no bitbucket token found"
+\`\`\`
+
+- If a **\`BITBUCKET_DATA_CENTER_TOKEN\`** variable is set (in any letter case) → you are on
+  **Bitbucket Data Center**.
+- Otherwise, if a **\`BITBUCKET_TOKEN\`** variable is set → you are on **Bitbucket Cloud**.
+- If neither is set, ask the user how they authenticate to Bitbucket before proceeding.
+
+When you reference the token later, use the exact variable name (and letter case) that
+actually exists in the environment.
+
+## Step 2 — Load the detailed skill
+
+Once you know the environment, use the \`invoke_skill\` tool to load the matching skill for
+full instructions on API calls, authenticated git remotes, and opening pull requests:
+
+- Bitbucket Cloud → invoke the **\`bitbucket-cloud\`** skill.
+- Bitbucket Data Center → invoke the **\`bitbucket-data-center\`** skill.
+
+## Quick reference (fallback)
+
+If you are unable to load the detailed skill, these are the essentials. Always use the
+Bitbucket API (not a web browser) and always use the listed PR tool to open a pull request.
+
+| | Bitbucket Cloud | Bitbucket Data Center |
+|---|---|---|
+| Token env var | \`BITBUCKET_TOKEN\` | \`BITBUCKET_DATA_CENTER_TOKEN\` |
+| Host | \`bitbucket.org\` | self-hosted domain |
+| REST API base | \`https://api.bitbucket.org/2.0\` | \`https://<host>/rest/api/1.0\` |
+| Repository identifier | \`workspace/repo_slug\` | \`PROJECT/repo_slug\` (project key) |
+| Pull request tool | \`create_bitbucket_pr\` | \`create_bitbucket_data_center_pr\` |`},{name:`bitbucket-cloud`,description:`Bitbucket Cloud (bitbucket.org) specifics — authenticate with BITBUCKET_TOKEN, use the REST API v2, workspace/repo_slug repositories, and the create_bitbucket_pr tool. Loaded on demand by the bitbucket skill once a Cloud environment is detected.`,triggers:[],content:'You are working with **Bitbucket Cloud** (`bitbucket.org`). You have access to an\nenvironment variable, `BITBUCKET_TOKEN`, which allows you to interact with the Bitbucket\nCloud API.\n\n- REST API base URL: `https://api.bitbucket.org/2.0`\n- Repository identifier format: `workspace/repo_slug`\n\n<IMPORTANT>\nYou can use `curl` with the `BITBUCKET_TOKEN` to interact with Bitbucket\'s API.\nALWAYS use the Bitbucket API for operations instead of a web browser.\nALWAYS use the `create_bitbucket_pr` tool to open a pull request\n</IMPORTANT>\n\nOnly rewrite the Bitbucket remote if a push actually fails with authentication errors and the user has asked you to push. Do not proactively rewrite `origin`. OpenHands OSS commonly stores `BITBUCKET_TOKEN` in the same unencoded `user:token` form used by commands such as `curl --user "$BITBUCKET_TOKEN" ...`, so keep it in that form unless you truly need to embed it in a Git remote URL.\n\nIf you need a non-interactive HTTPS remote URL, split `BITBUCKET_TOKEN` on the first `:` and URL-encode each part before calling `git remote set-url`. This avoids breaking usernames or emails that contain reserved URL characters such as `@`:\n\n```bash\nBB_USER="${BITBUCKET_TOKEN%%:*}" && \\\nBB_PASS="${BITBUCKET_TOKEN#*:}" && \\\nENCODED_USER=$(python3 -c \'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))\' "$BB_USER") && \\\nENCODED_PASS=$(python3 -c \'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))\' "$BB_PASS") && \\\ngit remote set-url origin "https://${ENCODED_USER}:${ENCODED_PASS}@bitbucket.org/username/repo.git"\n```\n\nPowerShell equivalent for the remote URL encoding:\n\n```powershell\n$parts = $env:BITBUCKET_TOKEN -split ":", 2\n$encodedUser = [Uri]::EscapeDataString($parts[0])\n$encodedPass = [Uri]::EscapeDataString($parts[1])\ngit remote set-url origin "https://${encodedUser}:${encodedPass}@bitbucket.org/username/repo.git"\n```\n\nAtlassian\'s Bitbucket Cloud docs recommend avoiding long-lived credentials in the remote URL when possible. Their API token examples use either `https://{bitbucket_username}:{api_token}@...` or `https://x-bitbucket-api-token-auth:{api_token}@...`; OpenHands users should only construct those URLs on demand, with proper URL encoding.\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_bitbucket_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\nOn Windows PowerShell, run those `git` commands as separate commands if `&&` is not supported by the installed shell.'},{name:`bitbucket-data-center`,description:`Bitbucket Data Center (self-hosted Bitbucket Server) specifics — authenticate with BITBUCKET_DATA_CENTER_TOKEN, use the REST API 1.0, PROJECT/repo_slug repositories, scm/ git remotes, and the create_bitbucket_data_center_pr tool. Loaded on demand by the bitbucket skill once a Data Center environment is detected.`,triggers:[],content:`You are working with **Bitbucket Data Center** (self-hosted Bitbucket Server). You have
+access to an environment variable, \`BITBUCKET_DATA_CENTER_TOKEN\`, which contains a basic
+auth token in the format \`username:your-token\` that allows you to interact with the git
+repository and the REST API.
+
+> Environment variable names are case-sensitive. If \`BITBUCKET_DATA_CENTER_TOKEN\` is not
+> present, use whichever case variant actually exists (for example
+> \`bitbucket_data_center_token\`). Run \`env | grep -i 'bitbucket_data_center'\` to find it.
+
+- REST API base URL: \`https://{domain}/rest/api/1.0\`
+- Repository identifier format: \`PROJECT/repo_slug\` (project key, slash, repo slug)
+
+You can use this token to interact with the Bitbucket Data Center REST API:
+\`\`\`bash
+curl -u "\${BITBUCKET_DATA_CENTER_TOKEN}" https://{domain}/rest/api/1.0/...
+\`\`\`
+
+<IMPORTANT>
+ALWAYS use the Bitbucket Data Center API for operations instead of a web browser.
+ALWAYS use the \`create_bitbucket_data_center_pr\` tool to open a pull request
+</IMPORTANT>
+
+If you encounter authentication issues when pushing to Bitbucket Data Center (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://\${BITBUCKET_DATA_CENTER_TOKEN}@{domain}/scm/{project_lower}/{repo}.git\`
+
+The token is a \`username:token\` pair, so if the username or token contains characters that are reserved in URLs (such as \`@\`), split on the first \`:\` and URL-encode each part before embedding it in a remote:
+
+\`\`\`bash
+BB_USER="\${BITBUCKET_DATA_CENTER_TOKEN%%:*}" && \\
+BB_PASS="\${BITBUCKET_DATA_CENTER_TOKEN#*:}" && \\
+ENCODED_USER=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_USER") && \\
+ENCODED_PASS=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_PASS") && \\
+git remote set-url origin "https://\${ENCODED_USER}:\${ENCODED_PASS}@{domain}/scm/{project_lower}/{repo}.git"
+\`\`\`
+
+Here are some instructions for pushing, but ONLY do this if the user asks you to:
+* NEVER push directly to the \`main\` or \`master\` branch
+* Git config (username and email) is pre-set. Do not modify.
+* You may already be on a branch starting with \`openhands-workspace\`. Create a new branch with a better name before pushing.
+* Use the \`create_bitbucket_data_center_pr\` tool to create a pull request, if you haven't already
+* 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.
+* Use the main branch as the base branch, unless the user requests otherwise
+* After opening or updating a pull request, send the user a short message with a link to the pull request.
+* Do NOT mark a pull request as ready to review unless the user explicitly says so
+* 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:
+\`\`\`bash
+git remote -v && git branch # to find the current org, repo and branch
+git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
+\`\`\``},{name:`code-review`,description:`Rigorous code review focusing on data structures, simplicity, security, pragmatism, and risk/safety evaluation. Provides brutally honest, actionable feedback on pull requests or merge requests, including a risk assessment for every review. Use when reviewing code changes.`,triggers:[`/codereview`,`/codereview-roasted`],content:`PERSONA:
 You are a critical code reviewer. Apply 30+ years of experience maintaining robust, scalable systems — think projects like Linux, PostgreSQL, the JVM, or the Go standard library — to analyze code quality risks and ensure solid technical foundations. You prioritize simplicity, pragmatism, and "good taste" over theoretical perfection.
 
 CORE PHILOSOPHY:
@@ -485,6 +654,7 @@ The prompt includes a **Files Changed** manifest listing every file in the PR, f
 3. Only after both checks come up empty should you flag something as missing. Even then, prefer "I could not locate X" over "X is missing" — the file may be in a path you haven't searched.
 
 Before posting an **inline review comment that names a specific line number**, verify the line maps to what you think it does (\`sed -n 'X,Yp' <file>\` or \`view\`). Line numbers derived by counting \`+\`/\`-\`/context lines from a \`@@\` hunk header are not reliable; ground them against the file.
+On Windows PowerShell, use \`Get-Content\`, \`Select-String\`, or \`(Get-Content <file>)[($start - 1)..($end - 1)]\` for the same file and line checks.
 
 CODE REVIEW SCENARIOS:
 
@@ -565,7 +735,7 @@ Require:
 8. **Dependency Changes**
 If dependency lock changes have downgraded a dependency, comment pointing that out to make sure it was intentional.
 
-When a PR adds a new dependency or bumps an existing one, review the upstream release for supply chain risk. If any target version was published less than 7 days ago, do **NOT** approve the PR yet — leave a blocking review comment and wait until the version is at least 7 days old. Read \`references/supply-chain-security.md\` for the full verification checklist including risk-based scrutiny tiers, concrete commands for checking release provenance, and escalation guidance.
+When a PR adds a new dependency or bumps an existing one, review the upstream release for supply chain risk. If any target version was published less than 7 days ago, do **NOT** approve the PR yet — leave a blocking review comment and wait until the version is at least 7 days old. First-party packages maintained by the same organization as the reviewed repository are intentionally excluded from the 7-day waiting rule, but still scrutinize them for supply-chain risk using the checklist. Read \`references/supply-chain-security.md\` for the full verification checklist including risk-based scrutiny tiers, concrete commands for checking release provenance, and escalation guidance.
 
 9. **Risk and Safety Evaluation**
 Read \`references/risk-evaluation.md\` for the full risk evaluation framework including risk levels (🟢 Low / 🟡 Medium / 🔴 High), risk factors, escalation guidance, and repo-specific risk rules.
@@ -740,6 +910,8 @@ When a review aspect has no findings, include it with an explicit "no issues fou
 - **\`references/code-quality-review.md\`** - Detailed criteria for naming, complexity, error handling, and project standards compliance
 - **\`references/efficiency-review.md\`** - Detailed criteria for algorithmic complexity, unnecessary work, resource usage, and I/O patterns`},{name:`datadog`,description:`Query and analyze Datadog logs, metrics, APM traces, and monitors using the Datadog API. Use when debugging production issues, monitoring application performance, or investigating alerts.`,triggers:[`datadog`],content:`# Datadog
 
+Windows PowerShell equivalents for the Datadog \`curl\`, environment-variable, timestamp, and JSON formatting snippets are in \`references/windows.md\`.
+
 <IMPORTANT>
 Before performing any Datadog operations, first check if the required environment variables are set:
 
@@ -952,6 +1124,8 @@ Use this skill when implementing or automating Discord integrations.
 
 ## Quick recipes
 
+The shell snippets below use POSIX-style environment variables and line continuations. On Windows PowerShell, use \`curl.exe\` for the shown flags and \`$env:DISCORD_WEBHOOK_URL\` / \`$env:DISCORD_BOT_TOKEN\` for environment variables, or translate the request to \`Invoke-RestMethod\`.
+
 ### Post a message via an incoming webhook (recommended)
 
 Discord requires at least one of \`content\`, \`embeds\`, \`components\`, \`file\`, or \`poll\`.
@@ -1023,13 +1197,17 @@ sudo dockerd > /tmp/docker.log 2>&1 &
 sleep 5
 \`\`\`
 
+On Windows, start Docker Desktop or the Docker service instead of running \`sudo dockerd\`; then run Docker commands from PowerShell without \`sudo\`.
+
 ## Verifying Docker Installation
 
 To verify Docker is working correctly, run the hello-world container:
 
 \`\`\`bash
 sudo docker run hello-world
-\`\`\``},{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\`.`},{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
 
@@ -1121,6 +1299,8 @@ Examples:
 - \`gh pr checks 200 --watch --interval 10\` to check until completed.
 </IMPORTANT>
 
+Windows PowerShell equivalents for the multi-line shell snippets below are in \`references/windows.md\`.
+
 If 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\`
 
 Here are some instructions for pushing, but ONLY do this if the user asks you to:
@@ -1240,6 +1420,7 @@ See [README.md](README.md) for the full debugging workflow, \`gh\` commands, and
 4. **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.`,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\`.
 
 ## Key Rule: One API Call
 
@@ -1420,6 +1601,7 @@ curl -X POST \\
 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.
+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
@@ -1658,6 +1840,7 @@ Each cron run executes \`main.py\`, which:
 
 Create a cron automation that polls a single GitHub repository on a
 configurable schedule (default: every minute).
+Windows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in \`references/windows.md\`.
 
 When a comment on an issue or PR contains the **trigger phrase**
 (default: \`@OpenHands\`) it:
@@ -1955,30 +2138,7 @@ Each cron run executes \`main.py\`, which:
 | Comments posted but no conversation created | Agent server URL wrong | Check \`OPENHANDS_URL\` secret and \`AGENT_SERVER_URL\` env var |
 | Same comment processed twice | \`processed_comment_ids\` cleared | State file was deleted; harmless but duplicate comment may appear |
 | Summary never posted | Conversation stuck in \`running\` | Open the conversation in the OpenHands UI; agent may need input |
-| 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`,description:`Interact with GitLab repositories, merge requests, and APIs using the GITLAB_TOKEN environment variable. Use when working with code hosted on GitLab or managing GitLab resources.`,triggers:[`gitlab`,`git`],content:`You have access to an environment variable, \`GITLAB_TOKEN\`, which allows you to interact with
-the GitLab API.
-
-<IMPORTANT>
-You can use \`curl\` with the \`GITLAB_TOKEN\` to interact with GitLab's API.
-ALWAYS use the GitLab API for operations instead of a web browser.
-ALWAYS use the \`create_mr\` tool to open a merge request
-</IMPORTANT>
-
-If you encounter authentication issues when pushing to GitLab (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://oauth2:\${GITLAB_TOKEN}@gitlab.com/username/repo.git\`
-
-Here are some instructions for pushing, but ONLY do this if the user asks you to:
-* NEVER push directly to the \`main\` or \`master\` branch
-* Git config (username and email) is pre-set. Do not modify.
-* You may already be on a branch starting with \`openhands-workspace\`. Create a new branch with a better name before pushing.
-* Use the \`create_mr\` tool to create a merge request, if you haven't already
-* Once you've created your own branch or a merge 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.
-* Use the main branch as the base branch, unless the user requests otherwise
-* After opening or updating a merge request, send the user a short message with a link to the merge request.
-* 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:
-\`\`\`bash
-git remote -v && git branch # to find the current org, repo and branch
-git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
-\`\`\``},{name:`incident-retrospective`,description:`Create an automation that drafts incident retrospectives. Gathers incident-channel messages from Slack, collects linked tickets and follow-ups from Linear, and publishes a retrospective draft to Notion with a timeline, impact summary, root-cause hypotheses, and action items.`,triggers:[`/incident-retro:setup`],content:`# Incident Retrospective Drafter Automation
+| 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`,description:`Interact with GitLab repositories, merge requests, and APIs using the GITLAB_TOKEN environment variable. Use when working with code hosted on GitLab or managing GitLab resources.`,triggers:[`gitlab`,`git`],content:"You have access to an environment variable, `GITLAB_TOKEN`, which allows you to interact with\nthe GitLab API.\n\n<IMPORTANT>\nYou can use `curl` with the `GITLAB_TOKEN` to interact with GitLab's API.\nALWAYS use the GitLab API for operations instead of a web browser.\nALWAYS use the `create_mr` tool to open a merge request\n</IMPORTANT>\n\nIf you encounter authentication issues when pushing to GitLab (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://oauth2:${GITLAB_TOKEN}@gitlab.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_mr` tool to create a merge request, if you haven't already\n* Once you've created your own branch or a merge 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 merge request, send the user a short message with a link to the merge request.\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\nOn Windows PowerShell, use `$env:GITLAB_TOKEN` in remote URLs and run the `git` commands as separate commands if `&&` is not supported by the installed shell."},{name:`incident-retrospective`,description:`Create an automation that drafts incident retrospectives. Gathers incident-channel messages from Slack, collects linked tickets and follow-ups from Linear, and publishes a retrospective draft to Notion with a timeline, impact summary, root-cause hypotheses, and action items.`,triggers:[`/incident-retro:setup`],content:`# Incident Retrospective Drafter Automation
 
 Set up an automation that drafts incident retrospectives by pulling data from
 Slack, Linear, and Notion.
@@ -2054,6 +2214,8 @@ curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \\
   }'
 \`\`\`
 
+PowerShell note: use \`curl.exe\` for this exact flag syntax, and replace \`\${OPENHANDS_HOST}\` / \`$OPENHANDS_AUTOMATION_API_KEY\` with \`$env:OPENHANDS_HOST\` / \`$env:OPENHANDS_AUTOMATION_API_KEY\` if running it natively.
+
 ### Step 5 — Confirm
 
 Tell the user:
@@ -2074,6 +2236,7 @@ No scripts — you are the orchestration loop. Uses only standard \`gh\` CLI
 commands that work on any GitHub repo.
 
 Requires: \`gh\` CLI authenticated with repo access, a PR branch.
+Windows PowerShell equivalents for Bash-only assignment, redirection, and quoting patterns in this skill are in \`references/windows.md\`.
 
 ## Discover what the repo has
 
@@ -2449,7 +2612,209 @@ Final summary should include:
 ## References
 
 - Verification stack (layers, signals, retriggering): \`references/verification.md\`
-- CI/review heuristics and decision tree: \`references/heuristics.md\``},{name:`jupyter`,description:`Read, modify, execute, and convert Jupyter notebooks programmatically. Use when working with .ipynb files for data science workflows, including editing cells, clearing outputs, or converting to other formats.`,triggers:[`ipynb`,`jupyter`],content:`# Jupyter Notebook Guide
+- CI/review heuristics and decision tree: \`references/heuristics.md\``},{name:`jira-issue-to-pr`,description:`This skill should be used when the user asks to "set up a Jira automation to create pull requests", "poll Jira for create-pr issues", "automatically create GitHub PRs from Jira tickets", "deploy a Jira issue-to-PR automation", "create a Jira to GitHub PR workflow", or mentions automating GitHub PR creation from a Jira label. Deploys a cron-based OpenHands automation that watches a Jira Cloud project for issues labeled with a configurable label (default: "create-pr") and spawns an agent conversation to create a GitHub pull request for each new issue found. The target GitHub repository is read from the body of the Jira ticket - no repo parameter is required at deploy time.`,triggers:[],content:`# Jira → GitHub PR Automation
+
+Deploys a cron automation that polls a Jira Cloud instance for open issues carrying a
+configurable label and, for each new issue, starts an OpenHands agent conversation that
+clones the GitHub repository specified in the ticket body, creates a branch, implements
+or placeholders the requested change, and opens a pull request. Once the conversation
+starts, it also posts a comment on the Jira ticket: "I'm on it: &lt;conversation URL&gt;".
+
+## How It Works
+
+1. **Poll** - every N minutes, \`POST /rest/api/3/search/jql\` on the Jira Cloud instance
+   to find open issues with the configured label.
+2. **Deduplicate** - on the very first run the script records a \`first_run_at\` baseline
+   timestamp in the KV store; any issue whose \`updated\` timestamp predates that baseline
+   is skipped (no backfill blast on first deploy). Using \`updated\` rather than \`created\`
+   means an old issue that has its label added after the automation is deployed will still
+   be picked up. Subsequent runs filter by both \`first_run_at\` and a KV-backed set of
+   already-processed issue keys. A \`max_new_per_run\` cap (default 5) limits conversations
+   started per cron firing as additional defense-in-depth.
+3. **Dispatch** - for each new issue, call \`POST /api/conversations\` on the agent server
+   to start an independent agent conversation with a PR-creation prompt. The prompt
+   instructs the agent to extract the target GitHub repository (\`owner/repo\`) from the
+   ticket body.
+4. **Comment** - immediately after the conversation is created, post a Jira comment on the
+   issue: \`I'm on it: <conversation URL>\`.
+5. **Persist** - record the processed issue key so re-runs never duplicate work.
+
+The polling run is lightweight (stdlib only, no SDK install); LLM costs are incurred only
+when new issues are actually found.
+
+## Prerequisites
+
+Before deploying, ensure the following are in place:
+
+| Requirement | Details |
+|---|---|
+| **Jira API token** | Stored as an OpenHands secret (see [Jira API token setup](#jira-api-token)) |
+| **GitHub token** | Must be stored as an OpenHands secret with \`repo\` + \`workflow\` scope so the spawned conversation can push branches and open PRs |
+| **Jira label** | The label to watch for (default: \`create-pr\`) must exist in the Jira project |
+| **GitHub repo** | The target repository must exist and the GitHub token must have write access |
+
+## Deploying the Automation
+
+### Step 1 - Collect parameters
+
+Gather the following from the user before proceeding:
+
+| Parameter | Example | Notes |
+|---|---|---|
+| \`jira_base_url\` | \`https://acme.atlassian.net\` | No trailing slash |
+| \`jira_email\` | \`alice@acme.com\` | Atlassian account email for Basic auth |
+| \`jira_token_secret\` | \`JIRA_CLOUD_KEY\` | Name of the OpenHands secret holding the API token |
+| \`jira_label\` | \`create-pr\` | Label to watch for (optional, defaults to \`create-pr\`) |
+| \`max_new_per_run\` | \`5\` | Max conversations dispatched per cron firing (optional, defaults to \`5\`) |
+| \`cron_schedule\` | \`*/5 * * * *\` | Polling frequency in cron syntax |
+
+> **Note**: The GitHub repository is not configured here. Each Jira ticket body must include
+> a reference to the target GitHub repo in \`owner/repo\` format (e.g. \`acme-org/backend\`).
+> The spawned agent extracts it from the ticket text.
+
+### Step 2 - Create config.json
+
+Create \`config.json\` next to \`scripts/main.py\` when packaging:
+
+\`\`\`json
+{
+  "jira_base_url":     "https://acme.atlassian.net",
+  "jira_email":        "alice@acme.com",
+  "jira_token_secret": "JIRA_CLOUD_KEY",
+  "jira_label":        "create-pr",
+  "max_new_per_run":   5
+}
+\`\`\`
+
+### Step 3 - Package the tarball
+
+Copy \`scripts/main.py\` from this skill and package it with the \`config.json\`:
+
+\`\`\`bash
+WORK=$(mktemp -d)
+cp <skill-dir>/scripts/main.py "$WORK/main.py"
+# write config.json into $WORK/config.json (see Step 2)
+tar -czf /tmp/jira-issue-to-pr.tar.gz -C "$WORK" .
+python3 -m py_compile "$WORK/main.py"   # validate syntax before uploading
+\`\`\`
+
+### Step 4 - Upload the tarball
+
+\`\`\`bash
+TARBALL_PATH=$(curl -s -X POST \\
+  "http://localhost:8000/api/automation/v1/uploads?name=jira-issue-to-pr" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/gzip" \\
+  --data-binary @/tmp/jira-issue-to-pr.tar.gz \\
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['tarball_path'])")
+\`\`\`
+
+### Step 5 - Create the automation
+
+\`\`\`bash
+curl -s -X POST "http://localhost:8000/api/automation/v1" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d "{
+    \\"name\\": \\"Jira issue-to-PR Poller\\",
+    \\"trigger\\": {
+      \\"type\\":     \\"cron\\",
+      \\"schedule\\": \\"*/5 * * * *\\",
+      \\"timezone\\": \\"UTC\\"
+    },
+    \\"tarball_path\\": \\"$TARBALL_PATH\\",
+    \\"entrypoint\\":   \\"python3 main.py\\",
+    \\"timeout\\":      540
+  }" | python3 -m json.tool
+\`\`\`
+
+Save the returned \`id\` - use it for updates and monitoring.
+
+### Step 6 - Verify with a test dispatch
+
+\`\`\`bash
+curl -s -X POST \\
+  "http://localhost:8000/api/automation/v1/<AUTOMATION_ID>/dispatch" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" | python3 -m json.tool
+
+# After ~30 seconds, check the run status:
+curl -s "http://localhost:8000/api/automation/v1/<AUTOMATION_ID>/runs?limit=1" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  | python3 -c "import sys,json; r=json.load(sys.stdin)['runs'][0]; print(r['status'], r.get('error_detail'))"
+\`\`\`
+
+## Updating an Existing Deployment
+
+To change configuration or update the script:
+
+1. Edit \`config.json\` with new values.
+2. Repackage and upload a new tarball (Steps 3-4 above).
+3. PATCH the existing automation with the new \`tarball_path\`:
+
+\`\`\`bash
+curl -s -X PATCH \\
+  "http://localhost:8000/api/automation/v1/<AUTOMATION_ID>" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d "{\\"tarball_path\\": \\"<NEW_TARBALL_PATH>\\"}"
+\`\`\`
+
+## Resetting Processed State
+
+To reprocess issues that were already handled (e.g., after testing), clear the KV store:
+
+\`\`\`bash
+curl -s -X DELETE \\
+  "http://localhost:8000/api/automation/v1/<KV_BASE>/v1/kv/state" \\
+  -H "Authorization: Bearer $AUTOMATION_KV_TOKEN"
+\`\`\`
+
+Or delete and recreate the automation to start with a clean state.
+
+## Script Reference
+
+The automation script lives at \`scripts/main.py\`. Key behaviors:
+
+- **No SDK dependencies** - pure Python stdlib; no \`setup.sh\` or \`uv\` install needed.
+- **Config file** - reads all parameters from \`config.json\` co-located with the script.
+- **First-run baseline** - on the very first execution the script writes \`first_run_at\` (UTC timestamp) into the KV store and exits without dispatching; issues whose \`updated\` timestamp predates that baseline are skipped on all subsequent runs. Using \`updated\` (not \`created\`) means an old issue that has its label applied after deployment is correctly treated as new.
+- **Per-run cap** - \`max_new_per_run\` (default 5) limits how many conversations are started per cron firing; any remaining new issues are dispatched on the next run.
+- **KV store** - persists \`{"processed_keys": [...], "first_run_at": "..."}\` between runs; falls back to a local file in dev environments where \`AUTOMATION_KV_TOKEN\` is absent.
+- **Jira API** - uses \`POST /rest/api/3/search/jql\` (the current non-deprecated endpoint).
+- **Conversation dispatch** - calls \`POST /api/conversations\` on the agent server with the current user's LLM/agent settings forwarded to the new conversation.
+- **Error transparency** - captures Jira HTTP response bodies in error messages for fast diagnosis.
+
+## Known Limitations
+
+### Pre-existing issues updated after deployment
+
+The deduplication filter compares each issue's \`fields.updated\` timestamp against
+\`first_run_at\`. \`updated\` is Jira's last-modified timestamp for the issue as a whole —
+it advances whenever **any** field changes (comments, priority, description, status, etc.),
+not only when the \`create-pr\` label is applied.
+
+This means a pre-existing issue that already carried the label at deployment time can
+slip through the filter if it is later updated for an unrelated reason (e.g. someone adds
+a comment), because its \`updated\` timestamp will have advanced past \`first_run_at\` while
+its key is not yet in \`processed_keys\`.
+
+**Workaround:** The only fully reliable way to detect exactly when a label was applied
+is the Jira changelog API (\`GET /rest/api/3/issue/{key}/changelog\`), which requires an
+extra HTTP call per issue. To avoid that overhead, keep the automation's scope narrow:
+use a label that is exclusively added as a PR-creation signal and is not already present
+on issues at the time of deployment.
+
+Once an issue is successfully dispatched its key is written to \`processed_keys\` in the
+KV store and is **permanently skipped on every future run** — regardless of subsequent
+label changes, comments, or any other updates to the issue. The only way to re-trigger a
+previously processed issue is to manually clear the KV store or delete and recreate the
+automation. This means the risk window described above is finite: as soon as the
+automation processes a pre-existing issue (even accidentally), it will never dispatch
+that issue again.
+
+## Additional Resources
+
+- **\`references/setup.md\`** - Jira API token creation, GitHub token scopes, cron schedule reference, and troubleshooting guide.`},{name:`jupyter`,description:`Read, modify, execute, and convert Jupyter notebooks programmatically. Use when working with .ipynb files for data science workflows, including editing cells, clearing outputs, or converting to other formats.`,triggers:[`ipynb`,`jupyter`],content:`# Jupyter Notebook Guide
 
 Notebooks are JSON files. Cells are in \`nb['cells']\`, each has \`source\` (list of strings) and \`cell_type\` ('code', 'markdown', or 'raw').
 
@@ -2476,6 +2841,12 @@ jupyter nbconvert --to markdown notebook.ipynb  # Convert to Markdown
 grep -n "search_term" notebook.ipynb
 \`\`\`
 
+PowerShell equivalent:
+
+\`\`\`powershell
+Select-String -Path notebook.ipynb -Pattern "search_term"
+\`\`\`
+
 ## Cell Structure
 \`\`\`python
 # Code cell
@@ -2497,6 +2868,7 @@ for cell in nb['cells']:
 KIND (Kubernetes IN Docker) is a tool for running local Kubernetes clusters using Docker containers as nodes. It's designed for testing Kubernetes applications locally.
 
 IMPORTANT: Before you proceed with installation, make sure you have docker installed locally.
+Windows PowerShell equivalents for installing KIND and kubectl are in \`references/windows.md\`.
 
 ### Installation
 
@@ -2706,6 +3078,8 @@ Handle these common edge cases gracefully:
 For posting structured code reviews, see the \`github-pr-review\` skill.
 For creating new skills, see the \`skill-creator\` skill.`},{name:`linear`,description:`Interact with Linear project management - query issues, update status, create tickets, and manage workflows using the Linear GraphQL API. Use when working with Linear tickets, sprints, or project tracking.`,triggers:[`linear`,`ticket`,`issue tracking`],content:`# Linear
 
+Windows PowerShell equivalents for the repeated Linear GraphQL \`curl\` and environment-variable snippets are in \`references/windows.md\`.
+
 <IMPORTANT>
 Before performing any Linear operations, check if the required environment variable is set:
 
@@ -2978,6 +3352,8 @@ curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \\
   }'
 \`\`\`
 
+PowerShell note: use \`curl.exe\` for this exact flag syntax, and replace \`\${OPENHANDS_HOST}\` / \`$OPENHANDS_AUTOMATION_API_KEY\` with \`$env:OPENHANDS_HOST\` / \`$env:OPENHANDS_AUTOMATION_API_KEY\` if running it natively.
+
 ### Step 5 — Confirm
 
 Tell the user:
@@ -2988,6 +3364,8 @@ Tell the user:
 > - Mode: \`{auto-apply or suggest}\`
 > - Trigger: \`{trigger description}\``},{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\`.
+
 <IMPORTANT>
 If authenticated Notion MCP tools are available in the environment, use them first. MCP tools do not require passing \`NOTION_INTEGRATION_KEY\` as a tool argument; authentication is handled by the configured MCP integration.
 
@@ -3089,6 +3467,7 @@ curl -s -X PATCH "https://api.notion.com/v1/blocks/\${PAGE_ID}/children" \\
 - Create a page: https://developers.notion.com/reference/post-page
 - Append block children: https://developers.notion.com/reference/patch-block-children`},{name:`npm`,description:`Handle npm package installation in non-interactive environments by piping confirmations. Use when installing Node.js packages that require user confirmation prompts.`,triggers:[`npm`],content:`When using npm to install packages, you will not be able to use an interactive shell, and it may be hard to confirm your actions.
 As an alternative, you can pipe in the output of the unix "yes" command to confirm your actions.`},{name:`openhands-api`,description:`Reference skill for the OpenHands Cloud REST API (V1) and agent-server APIs, including how to start additional cloud or local backend conversations for fresh-context or delegated work.`,triggers:[`openhands-api`,`openhands-api-v1`,`openhands-cloud`,`openhands-cloud-api-v1`,`oh-api-v1`,`oh-cloud-api-v1`],content:`This skill documents the **OpenHands Cloud API** (V1), commonly used **agent-server APIs**, and small, easy-to-copy clients.
+Windows PowerShell equivalents for the shell examples in this skill are in \`references/windows.md\`.
 
 It is intentionally focused on common OpenHands API workflows:
 
@@ -3546,6 +3925,7 @@ This skill is aligned against the current OpenHands API docs and implementation:
 - \`OpenHands/OpenHands/openhands/app_server/app_conversation/app_conversation_models.py\``},{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\`.
 
 ## Automation Creation Process
 The agent must follow these steps when creating an automation:
@@ -4519,7 +4899,6 @@ print("All done!")
 - [Send Message While Running](https://docs.openhands.dev/sdk/guides/convo-send-message-while-running.md): Interrupt running agents to provide additional context or corrections.
 - [Software Agent SDK](https://docs.openhands.dev/sdk.md): Build AI agents that write software. A clean, modular SDK with production-ready tools.
 - [Stuck Detector](https://docs.openhands.dev/sdk/guides/agent-stuck-detector.md): Detect and handle stuck agents automatically with timeout mechanisms.
-- [Sub-Agent Delegation](https://docs.openhands.dev/sdk/guides/agent-delegation.md): Enable parallel task execution by delegating work to multiple sub-agents that run independently and return consolidated results.
 - [Task Tool Set](https://docs.openhands.dev/sdk/guides/task-tool-set.md): Delegate complex work to specialized sub-agents that run synchronously and return results to the parent agent.
 - [Theory of Mind (TOM) Agent](https://docs.openhands.dev/sdk/guides/agent-tom-agent.md): Enable your agent to understand user intent and preferences through Theory of Mind capabilities, providing personalized guidance based on user modeling.
 - [TODO Management](https://docs.openhands.dev/sdk/guides/github-workflows/todo-management.md): Implement TODOs using OpenHands Agent
@@ -4631,6 +5010,8 @@ Source: [\`examples/\`](https://github.com/OpenHands/software-agent-sdk/tree/mai
 apt-get install texlive-latex-base
 \`\`\`
 
+On Windows, install MiKTeX or TeX Live with the native installer or a package manager such as \`winget\`. The \`apt-get\` commands only work in Linux or WSL.
+
 * Also install the recommended and extra fonts to avoid running into errors, when trying to use pdflatex on latex files with more fonts.
 
 \`\`\`
@@ -4649,7 +5030,71 @@ Once installed as above, you may be able to create PDF files from latex sources
 pdflatex latex_source_name.tex
 \`\`\`
 
-Ref: http://kkpradeeban.blogspot.com/2014/04/installing-latexpdflatex-on-ubuntu.html`},{name:`prd`,description:`"Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD."`,triggers:[`create a prd`,`write prd`,`plan this feature`,`requirements for`,`spec out`,`/prd`],content:`# PRD Generator
+Ref: http://kkpradeeban.blogspot.com/2014/04/installing-latexpdflatex-on-ubuntu.html`},{name:`plain-english-content`,description:`This skill should be used when the user asks to "write in plain English", "make this easier to read", "rewrite guidance", "improve report clarity", or produce accessible public-facing prose. It applies plain English content design principles: active voice, front-loaded content, sentence case, and no bold or italics for emphasis.`,triggers:[`plain English`],content:`Open content up so anyone can understand it the first time they read it, without losing substance, nuance or precision. Aim to open up, not dumb down. Apply the GOV.UK style guide approach: plain English, user needs first, active voice, front-loaded structure and accessible formatting.
+
+Use this skill for reports, research write-ups, guidance, documentation, summaries, and public-facing prose where clarity and accessibility matter. When writing a report, default to this style. When briefing a research agent, pass this skill so the report follows the same style.
+
+## Content design principles
+
+- Start from the user need. Write what the reader needs to know to do or decide something, not what the writer wants to say.
+- Front-load everything. Put the most important point first in the document, each section, each paragraph and each sentence. Use the inverted pyramid: conclusion first, then detail, then background.
+- Keep one idea per sentence and one topic per paragraph. Split sentences that contain more than one idea.
+- Be specific and concrete. Give the number, name and date. Cut vague abstractions like "a range of", "going forward" and "in terms of".
+- Cut everything that does not add meaning. Shorter is clearer. Remove duplication.
+
+## Plain English
+
+- Open content up, do not dumb it down. Keep the substance, nuance and precision. Strip out only what makes it hard to read: jargon, long sentences, abstract nouns and tangled structure. Make the content clear enough for a non-specialist and precise enough for an expert.
+- Use the active voice. Say who does what. Write "We reviewed the data", not "The data was reviewed".
+- Keep sentences short: about 15 to 20 words, and rarely more than 25. Keep paragraphs short.
+- Use everyday words. Replace jargon and formal wording with plain alternatives:
+  - use, not utilise or leverage
+  - help, not facilitate or empower
+  - work with, not collaborate, liaise or engage with
+  - make or provide, not deliver
+  - about, not in relation to or with regard to
+  - so, not in order to
+  - start, not commence
+  - end, not terminate
+  - buy, not purchase
+  - enough, not sufficient
+  - solve, fix or deal with, not tackle or combat
+  - effect on, not impact on
+- Do not use impact as a verb.
+- Avoid metaphors and cliches: drive, unlock, deep dive, robust, key, ring-fence, hub, portal, landscape, ecosystem and going forward.
+- Address the reader as "you". Write about the organisation as "we". Use "they", "them" and "their" rather than gendered pronouns. Write "disabled people", not "the disabled".
+- Use contractions for a warmer tone when appropriate, such as "we'll" and "you'll". Avoid negative contractions: write "cannot", not "can't". Avoid "should've", "could've" and "would've".
+
+## Formatting
+
+- Do not use bold or italics for emphasis. Plain words and good structure carry the meaning. Use bold only for a literal interface element in an instruction, for example: select Save. Use single quotation marks for the titles of schemes or documents, not italics.
+- Use sentence case everywhere: headings, titles and table headers. Capitalise only proper nouns.
+- Front-load headings, keep them under about 65 characters, and make them unique and descriptive. Do not use a full stop, dash, slash or question mark in headings. Use headings to help readers skim.
+- Introduce bullet lists with a lead-in line that ends in a colon. Start each bullet lowercase. Keep each bullet to one idea. Do not put "and" or "or" after each bullet. Do not use semicolons. Do not use a full stop after the last bullet unless the bullet is a full sentence.
+- Use a numbered list only for steps readers must follow in order. Write steps as full sentences that end with a full stop. Do not use a lead-in colon.
+- Use descriptive link text that says where the link goes and front-loads the key words. Never write "click here" or "read more". Make link text understandable out of context.
+- Do not use Latin abbreviations. Write "for example" not "eg", "that is" not "ie", and "and so on" or "such as" not "etc". Latin abbreviations confuse some readers and screen readers.
+- Write "and", not "&", except in a registered name or logo.
+- Write "one", but use numerals from 2 upwards. Use the % symbol with numerals, such as 50%. Use £ with no decimals unless there are pence: £75, £75.50. Spell out millions and billions, such as £5 million. Write ranges with "to", not a hyphen: 10 to 20, Monday to Friday.
+- Write dates as "4 June 2026" with no comma or ordinal suffix. Use "to" for ranges, such as "4 to 8 June". Write times as "10am to 11.30am". Use "midday" and "midnight".
+- Do not use FAQs when the content can meet the user need directly. Do not use exclamation marks. Do not use all caps for emphasis.
+
+## Before finishing: self-check
+
+- Is the single most important thing first?
+- Could a non-expert understand every sentence on first read?
+- Is every sentence active, short and focused on one idea?
+- Have all bold or italic emphasis, jargon, Latin abbreviations and marketing language been removed?
+- Is everything in sentence case, with descriptive headings and links?
+- Can any more words be cut without losing meaning? If yes, cut them.
+
+## Scope note
+
+The no-bold and formatting rules apply to produced prose, such as reports, guidance and summaries. Keep the conventions of code, data tables and direct quotations. Markdown headings and lists are acceptable because they provide structure, not emphasis.
+
+## Source
+
+Imported and adapted from the public gist at https://gist.github.com/fofr/505e225f9bf5e839d30c12ba6bfa0be2.`,license:`MIT`},{name:`prd`,description:`"Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD."`,triggers:[`create a prd`,`write prd`,`plan this feature`,`requirements for`,`spec out`,`/prd`],content:`# PRD Generator
 
 Create detailed Product Requirements Documents that are clear, actionable, and suitable for implementation.
 
@@ -5184,6 +5629,8 @@ curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \\
   }'
 \`\`\`
 
+PowerShell note: use \`curl.exe\` for this exact flag syntax, and replace \`\${OPENHANDS_HOST}\` / \`$OPENHANDS_AUTOMATION_API_KEY\` with \`$env:OPENHANDS_HOST\` / \`$env:OPENHANDS_AUTOMATION_API_KEY\` if running it natively.
+
 ### Step 5 — Confirm
 
 Tell the user:
@@ -5217,6 +5664,7 @@ You should always complete the task requested. If there are security concerns pl
 - Use secure error reporting mechanisms`},{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
 
 This skill provides guidance for creating effective skills.
+Windows PowerShell equivalents for the Unix shell commands used in examples are in \`references/windows.md\`.
 
 ## About Skills
 
@@ -5756,6 +6204,7 @@ To create a skill:
 Focus on strong trigger descriptions, progressive disclosure, and imperative writing style for effective skills that load when needed and provide targeted guidance.`},{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\`.
 When a message containing the **trigger phrase** (default: \`@openhands\`) is
 detected it:
 
@@ -6113,6 +6562,8 @@ curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \\
   }'
 \`\`\`
 
+PowerShell note: use \`curl.exe\` for this exact flag syntax, and replace \`\${OPENHANDS_HOST}\` / \`$OPENHANDS_AUTOMATION_API_KEY\` with \`$env:OPENHANDS_HOST\` / \`$env:OPENHANDS_AUTOMATION_API_KEY\` if running it natively.
+
 ### Step 5 — Confirm
 
 Tell the user:
@@ -6153,6 +6604,7 @@ https://spark.apache.org/docs/latest/migration-guide.html
 - [ ] Identify target Spark version
 - [ ] Search for deprecated APIs: \`grep -rn 'import org.apache.spark' --include='*.scala' --include='*.java' --include='*.py'\`
 - [ ] List all Spark config properties: \`grep -rn 'spark\\.' --include='*.conf' --include='*.properties' --include='*.scala' --include='*.java' --include='*.py' | grep -v 'test'\`
+- [ ] On Windows PowerShell, use \`Get-ChildItem -Recurse -Include *.scala,*.java,*.py | Select-String 'import org.apache.spark'\` and adjust the extensions/pattern for config searches.
 - [ ] Check for custom \`SparkSession\` or \`SparkContext\` extensions
 - [ ] Identify connector dependencies (Hive, Kafka, Cassandra, Delta, Iceberg)
 - [ ] Document findings in \`spark_upgrade_impact.md\`
@@ -6342,6 +6794,7 @@ Spark SQL behavior changes between versions can silently alter query results.
 ✓ Upgrade impact documented in \`spark_upgrade_impact.md\``,license:`MIT`,compatibility:`Requires Java 8+/11+/17+, Scala 2.12/2.13, Maven/Gradle/SBT, Apache Spark`},{name:`ssh`,description:`Establish and manage SSH connections to remote machines, including key generation, configuration, and file transfers. Use when connecting to remote servers, executing remote commands, or transferring files via SCP.`,triggers:[`ssh`,`remote server`,`remote machine`,`remote host`,`remote connection`,`secure shell`,`ssh keys`],content:`# SSH Skill
 
 This skill provides capabilities for establishing and managing SSH connections to remote machines.
+Windows PowerShell equivalents for SSH config creation, key paths, ssh-agent, and permissions are in \`references/windows.md\`.
 
 ## Capabilities
 
@@ -6465,6 +6918,7 @@ chmod 700 ~/.ssh
 This document provides instructions for installing Swift on Debian 12 (Bookworm).
 
 > This setup is intended for non-UI development tasks on Swift on Linux.
+> On Windows, run these Debian commands inside WSL2 or a Linux container. For native Windows Swift, use the Windows toolchain from Swift.org instead.
 
 ## Prerequisites
 
@@ -6702,6 +7156,11 @@ To allow agents and automated systems to access protected deployments, users nee
    \`\`\`bash
    curl -H "x-vercel-protection-bypass: <secret>" https://your-preview-url.vercel.app
    \`\`\`
+
+   PowerShell equivalent:
+   \`\`\`powershell
+   Invoke-WebRequest -Headers @{ "x-vercel-protection-bypass" = "<secret>" } -Uri https://your-preview-url.vercel.app
+   \`\`\`
    
    **As a Query Parameter:**
    \`\`\`