@openhands/extensions 0.6.0 → 0.7.0

package/integrations/catalog.schema.json

@@ -0,0 +1,255 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/OpenHands/extensions/integrations/catalog.schema.json",
+  "title": "IntegrationCatalogEntry",
+  "description": "Strict schema for integrations/catalog/*.json. Mirrors integrations/index.d.ts and encodes the cross-field connectability rules the catalog contract depends on.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "name", "description", "connectionOptions"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "categories": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "appUrl": { "type": "string", "pattern": "^https://", "minLength": 8 },
+    "docsUrl": { "type": "string", "pattern": "^https://", "minLength": 8 },
+    "notes": { "type": "string", "minLength": 1 },
+    "iconBg": { "type": "string", "minLength": 1 },
+    "iconColor": { "type": "string", "minLength": 1 },
+    "logoUrl": { "type": "string", "pattern": "^https://", "minLength": 8 },
+    "keywords": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "popularityRank": { "type": "integer", "minimum": 0 },
+    "installHint": { "type": "string", "minLength": 1 },
+    "connectionOptions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/connectionOption" }
+    }
+  },
+  "$defs": {
+    "marketplaceField": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "label"],
+      "properties": {
+        "key": { "type": "string", "minLength": 1 },
+        "label": { "type": "string", "minLength": 1 },
+        "type": { "enum": ["text", "password"] },
+        "placeholder": { "type": "string" },
+        "helperText": { "type": "string" },
+        "helperLink": { "type": "string", "pattern": "^https://" },
+        "required": { "type": "boolean" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "password" } } },
+          "then": {
+            "required": ["helperText"],
+            "properties": { "helperText": { "minLength": 1 } }
+          }
+        }
+      ]
+    },
+    "oauthConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "authorizationUrl": { "type": "string", "pattern": "^https://", "minLength": 8 },
+        "tokenUrl": { "type": "string", "pattern": "^https://", "minLength": 8 },
+        "scopes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "optionalScopes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "toolScopes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "scopeSeparator": { "enum": ["space", "comma"] },
+        "pkce": { "type": "boolean" },
+        "clientAuthentication": { "enum": ["basic", "body", "none"] },
+        "registrationUrl": { "type": "string", "pattern": "^https://", "minLength": 8 },
+        "additionalAuthorizationParams": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "additionalTokenParams": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "authConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["strategy"],
+      "properties": {
+        "strategy": { "enum": ["none", "api_key", "bearer", "basic", "oauth2"] },
+        "authModes": {
+          "type": "array",
+          "items": { "enum": ["none", "api_key", "bearer", "basic", "oauth2"] },
+          "minItems": 1
+        },
+        "credentialLabel": { "type": "string", "minLength": 1 },
+        "credentialPlaceholder": { "type": "string", "minLength": 1 },
+        "credentialHelp": { "type": "string", "minLength": 1 },
+        "credentialSecretName": { "type": "string", "minLength": 1 },
+        "saveCredentialAsSecretByDefault": { "type": "boolean" },
+        "apiKeyHeaderName": { "type": "string", "minLength": 1 },
+        "apiKeyOptional": { "type": "boolean" },
+        "oauth": { "$ref": "#/$defs/oauthConfig" }
+      }
+    },
+    "httpConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "apiBaseUrl": { "type": "string", "pattern": "^https://", "minLength": 8 },
+        "openApiUrl": { "type": "string", "pattern": "^https://", "minLength": 8 }
+      }
+    },
+    "transport": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "url"],
+          "properties": {
+            "kind": { "const": "shttp" },
+            "url": { "type": "string", "pattern": "^https://", "minLength": 8 },
+            "apiKeyOptional": { "type": "boolean" },
+            "headerFields": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/marketplaceField" }
+            },
+            "urlEditable": { "type": "boolean" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "url"],
+          "properties": {
+            "kind": { "const": "sse" },
+            "url": { "type": "string", "pattern": "^https://", "minLength": 8 },
+            "apiKeyOptional": { "type": "boolean" },
+            "headerFields": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/marketplaceField" }
+            },
+            "urlEditable": { "type": "boolean" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "serverName", "command", "args"],
+          "properties": {
+            "kind": { "const": "stdio" },
+            "serverName": { "type": "string", "minLength": 1 },
+            "command": { "type": "string", "minLength": 1 },
+            "args": {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 0
+            },
+            "envFields": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/marketplaceField" }
+            },
+            "argFields": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/marketplaceField" }
+            }
+          }
+        }
+      ]
+    },
+    "connectionOption": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "provider", "auth"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "provider": { "enum": ["mcp", "http"] },
+        "transport": { "$ref": "#/$defs/transport" },
+        "http": { "$ref": "#/$defs/httpConfig" },
+        "auth": { "$ref": "#/$defs/authConfig" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "provider": { "const": "mcp" } } },
+          "then": {
+            "required": ["transport"],
+            "not": { "required": ["http"] }
+          }
+        },
+        {
+          "if": { "properties": { "provider": { "const": "http" } } },
+          "then": {
+            "required": ["http"],
+            "not": { "required": ["transport"] },
+            "properties": {
+              "http": {
+                "required": ["apiBaseUrl", "openApiUrl"],
+                "properties": {
+                  "apiBaseUrl": { "type": "string", "minLength": 8 },
+                  "openApiUrl": { "type": "string", "minLength": 8 }
+                }
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "provider": { "const": "http" },
+              "auth": { "properties": { "strategy": { "const": "api_key" } } }
+            }
+          },
+          "then": {
+            "properties": {
+              "auth": { "required": ["apiKeyHeaderName"] }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "provider": { "const": "http" },
+              "auth": { "properties": { "strategy": { "const": "oauth2" } } }
+            }
+          },
+          "then": {
+            "properties": {
+              "auth": {
+                "required": ["oauth"],
+                "properties": {
+                  "oauth": {
+                    "required": ["authorizationUrl", "tokenUrl"],
+                    "properties": {
+                      "authorizationUrl": { "type": "string", "minLength": 8 },
+                      "tokenUrl": { "type": "string", "minLength": 8 }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/integrations/index.d.ts

@@ -15,11 +15,35 @@ export type IntegrationTransport =
       kind: "shttp";
       url: string;
       apiKeyOptional?: boolean;
+      /**
+       * Named request headers the user must supply (e.g. Datadog's
+       * `DD-API-KEY` / `DD-APPLICATION-KEY`). Values are sent verbatim as
+       * headers on every MCP request. The direct analog of stdio's
+       * `envFields`: each entry renders one input in the install modal,
+       * `type: "password"` entries are secret-saved by default, and
+       * `required` entries are validated before submit. Composes with the
+       * `api_key`/`bearer`/`basic` auth strategies (whose Bearer token is
+       * folded into `Authorization` separately); a header field with
+       * `key: "Authorization"` is redundant and should be avoided.
+       */
+      headerFields?: MarketplaceField[];
+      /**
+       * When true, the install modal renders the URL as an editable input
+       * pre-filled with `url` instead of read-only. Use for servers whose
+       * host is region/account-specific (e.g. Datadog's
+       * `https://mcp.<site>.datadoghq.com/v1/mcp`); pair with the entry's
+       * `installHint` to tell users what to change.
+       */
+      urlEditable?: boolean;
     }
   | {
       kind: "sse";
       url: string;
       apiKeyOptional?: boolean;
+      /** See {@link IntegrationTransport} `shttp` `headerFields`. */
+      headerFields?: MarketplaceField[];
+      /** See {@link IntegrationTransport} `shttp` `urlEditable`. */
+      urlEditable?: boolean;
     }
   | {
       kind: "stdio";
@@ -66,18 +90,9 @@ export interface IntegrationAuthConfig {
   oauth?: IntegrationOAuthConfig;
 }
 
-export interface IntegrationHttpDefaultTool {
-  name: string;
-  description?: string;
-  method?: string;
-  path?: string;
-  scopes?: string[];
-}
-
 export interface IntegrationHttpConfig {
   apiBaseUrl?: string;
   openApiUrl?: string;
-  defaultTool?: IntegrationHttpDefaultTool;
 }
 
 export interface IntegrationConnectionOption {
@@ -122,11 +137,12 @@ export const INTEGRATION_CATALOG: IntegrationCatalogEntry[];
 /**
  * Return the full integration catalog, optionally filtered by connector type.
  * Reads the generated static import index over `integrations/catalog/<id>.json`.
- * Returns the cached array; callers must treat it as read-only.
+ * Returns an independent copy, matching the Python read API.
  */
 export function listIntegrationCatalog(
   filter?: IntegrationCatalogFilter,
 ): IntegrationCatalogEntry[];
+/** Return one integration catalog entry by id as an independent copy. */
 export function getIntegrationCatalogEntry(
   id: string,
 ): IntegrationCatalogEntry | undefined;

package/integrations/index.js

@@ -7,6 +7,7 @@
  */
 import { INTEGRATION_CATALOG_ENTRIES } from "./catalog-index.js";
 
+const clone = (value) => JSON.parse(JSON.stringify(value));
 const INTEGRATIONS = INTEGRATION_CATALOG_ENTRIES;
 const INTEGRATION_BY_ID = new Map(INTEGRATIONS.map((entry) => [entry.id, entry]));
 
@@ -17,18 +18,25 @@ const entrySupportsOauth = (entry) =>
   entry.connectionOptions.some((option) => option.auth?.strategy === "oauth2");
 
 export const listIntegrationCatalog = (filter) => {
-  if (!filter) return INTEGRATIONS;
-  const { mcp, oauth } = filter;
-  if (mcp === undefined && oauth === undefined) return INTEGRATIONS;
-  return INTEGRATIONS.filter((entry) => {
-    const mcpOk = mcp === undefined || entrySupportsMcp(entry) === mcp;
-    const oauthOk = oauth === undefined || entrySupportsOauth(entry) === oauth;
-    return mcpOk && oauthOk;
-  });
+  const entries =
+    !filter || (filter.mcp === undefined && filter.oauth === undefined)
+      ? INTEGRATIONS
+      : INTEGRATIONS.filter((entry) => {
+          const mcpOk =
+            filter.mcp === undefined || entrySupportsMcp(entry) === filter.mcp;
+          const oauthOk =
+            filter.oauth === undefined ||
+            entrySupportsOauth(entry) === filter.oauth;
+          return mcpOk && oauthOk;
+        });
+  return clone(entries);
 };
 
-export const getIntegrationCatalogEntry = (id) => INTEGRATION_BY_ID.get(id);
+export const getIntegrationCatalogEntry = (id) => {
+  const entry = INTEGRATION_BY_ID.get(id);
+  return entry ? clone(entry) : undefined;
+};
 
-export const INTEGRATION_CATALOG = INTEGRATIONS;
+export const INTEGRATION_CATALOG = clone(INTEGRATIONS);
 
 export default INTEGRATION_CATALOG;

package/marketplaces/openhands-extensions.json

@@ -130,7 +130,7 @@
     {
       "name": "bitbucket",
       "source": "./skills/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.",
+      "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.",
       "category": "integration",
       "keywords": [
         "bitbucket",
@@ -138,6 +138,31 @@
         "pull-request"
       ]
     },
+    {
+      "name": "bitbucket-cloud",
+      "source": "./skills/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.",
+      "category": "integration",
+      "keywords": [
+        "bitbucket",
+        "bitbucket-cloud",
+        "git",
+        "pull-request"
+      ]
+    },
+    {
+      "name": "bitbucket-data-center",
+      "source": "./skills/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.",
+      "category": "integration",
+      "keywords": [
+        "bitbucket",
+        "bitbucket-data-center",
+        "bitbucket-server",
+        "git",
+        "pull-request"
+      ]
+    },
     {
       "name": "city-weather",
       "source": "./plugins/city-weather",

package/package.json

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

package/plugins/pr-review/scripts/prompt.py

@@ -76,7 +76,7 @@ PROMPT = """{skill_trigger}
 
 When posting a review, keep the review body brief unless your active review instructions require a longer structured format.
 
-For dependency update PRs, do **NOT** approve a target version that was published less than 7 days ago.
+For dependency update PRs, do **NOT** approve a target version that was published less than 7 days ago. First-party packages maintained by the same organization as the reviewed repository are intentionally excluded from this 7-day waiting rule, but still scrutinize them for supply-chain risk.
 
 Review the PR changes below and identify issues that need to be addressed.
 

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.6.0"
+version = "0.7.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 
@@ -19,6 +19,7 @@ test = [
     "pytest>=8.0",
     "requests>=2.31",
     "openhands-sdk>=0.3",
+    "jsonschema>=4.23",
 ]
 
 [tool.pytest.ini_options]

package/python/openhands_extensions/_version.py

@@ -16,7 +16,8 @@ from importlib.metadata import PackageNotFoundError, version
 
 #: Fallback used only when the package is not installed (no dist metadata).
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
-_FALLBACK_VERSION = "0.6.0"
+# x-release-please-update-version
+_FALLBACK_VERSION = "0.7.0"
 
 try:
     __version__: str = version("openhands-extensions")

package/skills/agent-canvas-environment/SKILL.md

@@ -50,12 +50,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
@@ -70,26 +86,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,
@@ -107,6 +154,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>`

package/skills/bitbucket/README.md

@@ -1,6 +1,7 @@
 # Bitbucket
 
-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.
+Bitbucket integration **hub** skill. It detects whether the repository is on Bitbucket
+Cloud or Bitbucket Data Center and directs the agent to the matching detailed skill.
 
 ## Triggers
 
@@ -9,42 +10,24 @@ This skill is activated by the following keywords:
 - `bitbucket`
 - `git`
 
-## Details
-
-You have access to an environment variable, `BITBUCKET_TOKEN`, which allows you to interact with
-the Bitbucket API.
-
-<IMPORTANT>
-You can use `curl` with the `BITBUCKET_TOKEN` to interact with Bitbucket's API.
-ALWAYS use the Bitbucket API for operations instead of a web browser.
-ALWAYS use the `create_bitbucket_pr` tool to open a pull request
-</IMPORTANT>
-
-Only 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 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.
-
-If 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 `@`:
-
-```bash
-BB_USER="${BITBUCKET_TOKEN%%:*}" && \
-BB_PASS="${BITBUCKET_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}@bitbucket.org/username/repo.git"
-```
-
-Atlassian'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.
-
-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_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
-```
+## Why a hub skill?
+
+Bitbucket ships as two products that behave differently — **Bitbucket Cloud**
+(`bitbucket.org`) and **Bitbucket Data Center** (self-hosted Bitbucket Server). They use
+different token environment variables, REST APIs, repository identifiers, git remote URL
+formats, and pull request tools.
+
+This hub triggers broadly (on `git`/`bitbucket`) so it loads for any Bitbucket task — even
+when the words "data center" never appear. It then:
+
+1. **Detects** the environment by checking which token variable is present
+   (`BITBUCKET_DATA_CENTER_TOKEN` → Data Center, else `BITBUCKET_TOKEN` → Cloud). The check
+   is case-insensitive so it is robust to env-var casing differences.
+2. **Hands off** to the matching detailed skill via the `invoke_skill` tool:
+   - Bitbucket Cloud → [`bitbucket-cloud`](../bitbucket-cloud/)
+   - Bitbucket Data Center → [`bitbucket-data-center`](../bitbucket-data-center/)
+
+The hub also carries a small quick-reference table as a fallback in case the detailed skill
+cannot be loaded.
+
+See [`SKILL.md`](SKILL.md) for the full content.