@openhands/extensions 0.0.1-alpha → 0.2.0

package/skills/linear/SKILL.md

@@ -0,0 +1,213 @@
+---
+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
+---
+
+# Linear
+
+<IMPORTANT>
+Before performing any Linear operations, check if the required environment variable is set:
+
+```bash
+[ -n "$LINEAR_API_KEY" ] && echo "LINEAR_API_KEY is set" || echo "LINEAR_API_KEY is NOT set"
+```
+
+If LINEAR_API_KEY is missing, ask the user to provide it before proceeding.
+</IMPORTANT>
+
+## Understanding Linear Identifiers
+
+Linear uses two types of identifiers for issues:
+
+- **Human-readable identifier** (e.g., `ALL-1234`): Displayed to users, used in search queries. This is the team key + number.
+- **UUID** (e.g., `a1b2c3d4-e5f6-7890-abcd-ef1234567890`): Required for all mutations (update, comment, etc.). Returned as `id` in query results.
+
+**Important workflow**: When working with issues, you must:
+1. Search or query using the human-readable identifier
+2. Extract the `id` (UUID) from the query result
+3. Use the UUID in any mutation operations
+
+## Authentication
+
+All Linear API requests use GraphQL with the API key in the Authorization header:
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{"query": "YOUR_GRAPHQL_QUERY"}'
+```
+
+## Common Queries
+
+### Get Assigned Issues (Open)
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "query { viewer { assignedIssues(first: 50, filter: { state: { type: { nin: [\"completed\", \"canceled\"] } } }) { nodes { id identifier title priority priorityLabel state { name type } description createdAt updatedAt } } } }"
+  }' | jq '.data.viewer.assignedIssues.nodes'
+```
+
+### Get Issues by Priority
+
+Priority values: 0 = No priority, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "query { viewer { assignedIssues(first: 50, filter: { priority: { lte: 2 }, state: { type: { nin: [\"completed\", \"canceled\"] } } }) { nodes { id identifier title priority priorityLabel state { name } } } } }"
+  }' | jq '.data.viewer.assignedIssues.nodes'
+```
+
+### Get Issue Details
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "query { issue(id: \"ISSUE_UUID\") { id identifier title description state { name } priority assignee { name email } labels { nodes { name } } comments { nodes { body createdAt user { name } } } } }"
+  }' | jq '.data.issue'
+```
+
+### Search Issues by Identifier
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "query { issueSearch(query: \"ALL-1234\", first: 5) { nodes { id identifier title state { name } } } }"
+  }' | jq '.data.issueSearch.nodes'
+```
+
+## Common Mutations
+
+### Update Issue State
+
+First, get available workflow states:
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "query { workflowStates { nodes { id name type } } }"
+  }' | jq '.data.workflowStates.nodes'
+```
+
+Then update the issue:
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "mutation { issueUpdate(id: \"ISSUE_UUID\", input: { stateId: \"STATE_UUID\" }) { success issue { identifier state { name } } } }"
+  }' | jq '.data.issueUpdate'
+```
+
+### Add Comment to Issue
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "mutation { commentCreate(input: { issueId: \"ISSUE_UUID\", body: \"Your comment here\" }) { success comment { id body } } }"
+  }' | jq '.data.commentCreate'
+```
+
+### Create New Issue
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "mutation { issueCreate(input: { teamId: \"TEAM_UUID\", title: \"Issue Title\", description: \"Issue description\", priority: 2 }) { success issue { identifier title url } } }"
+  }' | jq '.data.issueCreate'
+```
+
+## End-to-End Workflow: Move Issue to "In Progress"
+
+This example shows the complete flow to change an issue's state using its human-readable identifier:
+
+### Step 1: Search for the issue to get its UUID
+
+```bash
+# Search for issue ALL-1234 and extract its UUID
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "query { issueSearch(query: \"ALL-1234\", first: 1) { nodes { id identifier title state { name } } } }"
+  }' | jq '.data.issueSearch.nodes[0]'
+# Save the "id" value (UUID) from the response
+```
+
+### Step 2: Get available workflow states
+
+```bash
+# List all workflow states to find the "In Progress" state UUID
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "query { workflowStates { nodes { id name type } } }"
+  }' | jq '.data.workflowStates.nodes[] | select(.name == "In Progress")'
+# Save the "id" value of the desired state
+```
+
+### Step 3: Update the issue state
+
+```bash
+# Use the issue UUID and state UUID from previous steps
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "mutation { issueUpdate(id: \"ISSUE_UUID_FROM_STEP_1\", input: { stateId: \"STATE_UUID_FROM_STEP_2\" }) { success issue { identifier state { name } } } }"
+  }' | jq '.data.issueUpdate'
+```
+
+## Get Team Information
+
+```bash
+curl -s -X POST https://api.linear.app/graphql \
+  -H "Content-Type: application/json" \
+  -H "Authorization: $LINEAR_API_KEY" \
+  -d '{
+    "query": "query { teams { nodes { id name key } } }"
+  }' | jq '.data.teams.nodes'
+```
+
+## Priority Levels
+
+| Priority | Label | Recommended Action |
+|----------|-------|-------------------|
+| 1 | Urgent | Work on immediately |
+| 2 | High | Work on first |
+| 3 | Medium | Normal priority |
+| 4 | Low | When time permits |
+| 0 | None | Backlog |
+
+## State Types
+
+- `backlog` - Not yet started
+- `unstarted` - Todo
+- `started` - In Progress
+- `completed` - Done
+- `canceled` - Won't do
+
+## Documentation
+
+- [Linear API Documentation](https://developers.linear.app/docs/graphql/working-with-the-graphql-api)
+- [GraphQL Schema Reference](https://studio.apollographql.com/public/Linear-API/variant/current/schema/reference)

package/skills/linear-triage/.plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "linear-triage",
+  "version": "1.0.0",
+  "description": "Create an automation that triages new Linear issues by inspecting title, description, team, and recent related issues. Suggests labels, priority, likely owner, and potential duplicates, then posts a clarifying comment.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "linear",
+    "triage",
+    "issues",
+    "labels",
+    "priority",
+    "automation",
+    "integration"
+  ]
+}

package/skills/linear-triage/README.md

@@ -0,0 +1,34 @@
+# Linear Issue Triage
+
+Create an automation that triages new Linear issues with labels, priority, and owner suggestions.
+
+## Triggers
+
+This skill is activated by keywords:
+
+- `triage Linear issues`
+- `auto-label Linear`
+- `Linear triage automation`
+
+## Features
+
+- **Inspects issue title, description, team, and customer context**
+- **Suggests labels, priority, and likely owner**
+- **Detects potential duplicate issues**
+- **Posts a triage comment with rationale**
+- **Configurable**: auto-apply changes or suggest for approval
+
+## Prerequisites
+
+Linear MCP installed in Settings → MCP
+
+## Quick Start
+
+Ask OpenHands:
+
+> "Set up a triage automation for the Engineering team in Linear that
+> suggests labels and priority for new issues"
+
+## See Also
+
+- [SKILL.md](SKILL.md) — Full setup workflow reference

package/skills/linear-triage/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: linear-triage
+description: >
+  Create an automation that triages new Linear issues. Inspects the issue
+  title, description, team, customer, priority, and recent related issues via
+  Linear MCP. Suggests labels, priority, likely owner, duplicates, and posts
+  a clarifying comment.
+triggers:
+  - /linear-triage:setup
+---
+
+# Linear Issue Triage Automation
+
+Set up an automation that triages new Linear issues — classifying, labeling,
+and suggesting owners automatically.
+
+---
+
+## Prerequisites
+
+### Required integration
+
+- **Linear MCP** must be installed in Settings → MCP.
+
+### Information to collect
+
+Ask the user for:
+
+1. **Teams/projects** — which Linear teams or projects should be triaged (e.g. `Engineering`, `Support`)
+2. **Label taxonomy** — what labels are used for classification? (e.g. `bug`, `feature`, `support`, `chore`)
+3. **Priority conventions** — how does the team use priority levels? Any mapping rules?
+4. **Auto-apply or suggest** — should the automation apply labels/priority/assignee directly, or post a triage comment with suggestions for human approval?
+5. **Duplicate detection** — should it search for and flag potential duplicate issues?
+
+---
+
+## Setup Workflow
+
+### Step 1 — Verify Linear MCP access
+
+Confirm the Linear MCP integration is working:
+```
+Use the Linear MCP to list recent issues for one of the target teams.
+```
+
+If it fails, tell the user to install the Linear MCP integration first.
+
+### Step 2 — Determine trigger type
+
+**Event-based (recommended if publicly reachable):**
+Check `<RUNTIME_SERVICES>` for deployment reachability. If public, recommend an event trigger on Linear `Issue` create events.
+
+**Cron-based (local/private deployments):**
+Poll for recently created issues on a schedule (e.g. every 5 minutes).
+
+### Step 3 — Build the triage prompt
+
+Construct a prompt that includes:
+- Target teams/projects
+- Label taxonomy and classification rules
+- Priority mapping conventions
+- Whether to auto-apply or suggest
+- Duplicate detection preference
+
+### Step 4 — Create the automation
+
+Read the Automation backend URL and auth from `<RUNTIME_SERVICES>`:
+- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`
+- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`
+
+Use the **prompt preset** endpoint:
+```bash
+curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Linear Issue Triage",
+    "prompt": "<constructed triage prompt>",
+    "trigger": <trigger config from step 2>
+  }'
+```
+
+### Step 5 — Confirm
+
+Tell the user:
+> ✅ **Linear Issue Triage** is running!
+>
+> - Automation ID: `{id}`
+> - Teams: `{team list}`
+> - Mode: `{auto-apply or suggest}`
+> - Trigger: `{trigger description}`

package/skills/linear-triage/commands/linear-triage:setup.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Create an automation that triages new Linear issues. Inspects the issue title, description, team, customer, priority, and recent related issues via Linear MCP. Suggests labels, priority, likely owner, duplicates, and posts a clarifying comment.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS

package/skills/notion/.plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "notion",
+  "version": "1.0.0",
+  "description": "Create, search, and update Notion pages/databases using the Notion API. Use for documenting work, generating runbooks, and automating knowledge base updates.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "notion",
+    "documentation",
+    "knowledge-base"
+  ]
+}

package/skills/notion/README.md

@@ -0,0 +1,114 @@
+# Notion
+
+Create, search, and update Notion pages/databases using the Notion API. Use for documenting work, generating runbooks, and automating knowledge base updates.
+
+## Triggers
+
+This skill is activated by the following keywords:
+
+- `notion`
+
+## Details
+
+# Notion
+
+<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.
+
+Use the direct Notion REST API examples below only when MCP is unavailable or when you explicitly need raw API/curl access. For that direct-API path, first check whether the required environment variable is set:
+
+```bash
+[ -n "$NOTION_INTEGRATION_KEY" ] && echo "NOTION_INTEGRATION_KEY is set" || echo "NOTION_INTEGRATION_KEY is NOT set"
+```
+
+If it’s missing and you need the direct API path, ask the user to provide it (or connect a Notion integration) before proceeding:
+- **NOTION_INTEGRATION_KEY**: Notion integration secret (starts with `ntn_...`)
+
+Whether you use MCP or the direct API, also confirm the configured integration has been **shared** with the target page/database in Notion.
+</IMPORTANT>
+
+## Base headers for direct API calls
+
+```bash
+-H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
+-H "Notion-Version: 2022-06-28" \
+-H "Content-Type: application/json"
+```
+
+## Find a page (search)
+
+Use Notion’s search endpoint to find a page by title.
+
+```bash
+curl -s https://api.notion.com/v1/search \
+  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
+  -H "Notion-Version: 2022-06-28" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "OpenHands Wiki",
+    "page_size": 10
+  }' | jq .
+```
+
+## Create a page under a parent page
+
+```bash
+PARENT_PAGE_ID="<parent_page_id>"
+
+curl -s https://api.notion.com/v1/pages \
+  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
+  -H "Notion-Version: 2022-06-28" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parent": {"type": "page_id", "page_id": "'"${PARENT_PAGE_ID}"'"},
+    "properties": {
+      "title": {
+        "title": [{"type": "text", "text": {"content": "My new page"}}]
+      }
+    },
+    "children": [
+      {
+        "object": "block",
+        "type": "paragraph",
+        "paragraph": {
+          "rich_text": [{"type": "text", "text": {"content": "Hello from OpenHands."}}]
+        }
+      }
+    ]
+  }' | jq .
+```
+
+## Append blocks to an existing page
+
+Use the page’s block id (same as page id) to append children.
+
+```bash
+PAGE_ID="<page_id>"
+
+curl -s -X PATCH "https://api.notion.com/v1/blocks/${PAGE_ID}/children" \
+  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
+  -H "Notion-Version: 2022-06-28" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "children": [
+      {
+        "object": "block",
+        "type": "heading_2",
+        "heading_2": {"rich_text": [{"type": "text", "text": {"content": "Appended section"}}]}
+      }
+    ]
+  }' | jq .
+```
+
+## Tips / gotchas
+
+- **Sharing is required**: even with a valid key, the integration can’t see a page/database until it has been shared with the integration in the Notion UI.
+- **Rate limits**: keep requests small; for large pages, create the page first and then append blocks in batches.
+- **IDs format**: Notion IDs may be returned with dashes; both dashed and non-dashed forms typically work in API calls.
+
+## Documentation
+
+- Notion API: https://developers.notion.com/reference/intro
+- Search: https://developers.notion.com/reference/post-search
+- Create a page: https://developers.notion.com/reference/post-page
+- Append block children: https://developers.notion.com/reference/patch-block-children

package/skills/notion/SKILL.md

@@ -0,0 +1,109 @@
+---
+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
+---
+
+# Notion
+
+<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.
+
+Use the direct Notion REST API examples below only when MCP is unavailable or when you explicitly need raw API/curl access. For that direct-API path, first check whether the required environment variable is set:
+
+```bash
+[ -n "$NOTION_INTEGRATION_KEY" ] && echo "NOTION_INTEGRATION_KEY is set" || echo "NOTION_INTEGRATION_KEY is NOT set"
+```
+
+If it’s missing and you need the direct API path, ask the user to provide it (or connect a Notion integration) before proceeding:
+- **NOTION_INTEGRATION_KEY**: Notion integration secret (starts with `ntn_...`)
+
+Whether you use MCP or the direct API, also confirm the configured integration has been **shared** with the target page/database in Notion.
+</IMPORTANT>
+
+## Base headers for direct API calls
+
+```bash
+-H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
+-H "Notion-Version: 2022-06-28" \
+-H "Content-Type: application/json"
+```
+
+## Find a page (search)
+
+Use Notion’s search endpoint to find a page by title.
+
+```bash
+curl -s https://api.notion.com/v1/search \
+  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
+  -H "Notion-Version: 2022-06-28" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "OpenHands Wiki",
+    "page_size": 10
+  }' | jq .
+```
+
+## Create a page under a parent page
+
+```bash
+PARENT_PAGE_ID="<parent_page_id>"
+
+curl -s https://api.notion.com/v1/pages \
+  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
+  -H "Notion-Version: 2022-06-28" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parent": {"type": "page_id", "page_id": "'"${PARENT_PAGE_ID}"'"},
+    "properties": {
+      "title": {
+        "title": [{"type": "text", "text": {"content": "My new page"}}]
+      }
+    },
+    "children": [
+      {
+        "object": "block",
+        "type": "paragraph",
+        "paragraph": {
+          "rich_text": [{"type": "text", "text": {"content": "Hello from OpenHands."}}]
+        }
+      }
+    ]
+  }' | jq .
+```
+
+## Append blocks to an existing page
+
+Use the page’s block id (same as page id) to append children.
+
+```bash
+PAGE_ID="<page_id>"
+
+curl -s -X PATCH "https://api.notion.com/v1/blocks/${PAGE_ID}/children" \
+  -H "Authorization: Bearer ${NOTION_INTEGRATION_KEY}" \
+  -H "Notion-Version: 2022-06-28" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "children": [
+      {
+        "object": "block",
+        "type": "heading_2",
+        "heading_2": {"rich_text": [{"type": "text", "text": {"content": "Appended section"}}]}
+      }
+    ]
+  }' | jq .
+```
+
+## Tips / gotchas
+
+- **Sharing is required**: even with a valid key, the integration can’t see a page/database until it has been shared with the integration in the Notion UI.
+- **Rate limits**: keep requests small; for large pages, create the page first and then append blocks in batches.
+- **IDs format**: Notion IDs may be returned with dashes; both dashed and non-dashed forms typically work in API calls.
+
+## Documentation
+
+- Notion API: https://developers.notion.com/reference/intro
+- Search: https://developers.notion.com/reference/post-search
+- Create a page: https://developers.notion.com/reference/post-page
+- Append block children: https://developers.notion.com/reference/patch-block-children

package/skills/npm/.plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "npm",
+  "version": "1.0.0",
+  "description": "Handle npm package installation in non-interactive environments by piping confirmations. Use when installing Node.js packages that require user confirmation prompts.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "npm",
+    "nodejs",
+    "packages"
+  ]
+}

package/skills/npm/README.md

@@ -0,0 +1,14 @@
+# Npm
+
+Handle npm package installation in non-interactive environments by piping confirmations. Use when installing Node.js packages that require user confirmation prompts.
+
+## Triggers
+
+This skill is activated by the following keywords:
+
+- `npm`
+
+## Details
+
+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.

package/skills/npm/SKILL.md

@@ -0,0 +1,9 @@
+---
+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
+---
+
+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.

package/skills/openhands-api/.plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "openhands-api",
+  "version": "1.0.0",
+  "description": "Use the OpenHands Cloud REST API (V1) to create and manage app conversations, including multi-conversation delegation workflows, and to access sandbox agent-server endpoints. Includes minimal Pytho...",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "openhands",
+    "api",
+    "cloud",
+    "automation",
+    "delegation",
+    "agent-server",
+    "sandbox",
+    "conversations"
+  ]
+}