Bitbucket

Bitbucket Skill

This skill is one implementation of the repo capability in the Orbit shared provider framework. Core repository, branch, and pull request operations live here; repo required-reviewers, jira pr-issues, jira issue-commits, and similar bridge flows are optional Bitbucket-specific enhancements layered on top.

Use this skill to operate Bitbucket Data Center repositories, branches, and pull requests through the packaged launcher and local CLI runtime.

Runtime and execution

Always run the packaged launcher through ${BITBUCKET_SKILL_DIR} so it works from the user's current working directory:

• macOS/Linux: ${BITBUCKET_SKILL_DIR}/bin/bitbucket
• Windows: ${BITBUCKET_SKILL_DIR}\bin\bitbucket.cmd

${BITBUCKET_SKILL_DIR} is a documentation placeholder, not a guaranteed shell environment variable. Do not execute ${BITBUCKET_SKILL_DIR}/bin/bitbucket or ${BITBUCKET_SKILL_DIR}\bin\bitbucket.cmd literally when the host has not resolved that placeholder. Resolve BIN to a real launcher path once before the first CLI call. When the host leaves the placeholder unresolved, check the current workspace install first, such as .claude/skills/bitbucket/bin/bitbucket or .Codex/skills/bitbucket/bin/bitbucket, then fall back to the host-provided installed skill directory when available. Do not call node dist/cli.js directly. Do not start with version, doctor, or --help when the user already asked for a concrete Bitbucket read or write task, unless the launcher itself is failing. When exact command syntax is unclear, use the packaged launcher with <group> --help or <group> <action> --help before guessing flags. The launcher first reuses a compatible system Node runtime when available (currently Node >= 20), and only downloads the required runtime into the local cache when the machine does not already have one.

Scope and boundaries

• Bitbucket Data Center only (not Bitbucket Cloud).
• CLI-mediated operations only.
• Do not call Bitbucket REST API directly from the skill layer.
• The CLI may use explicitly allowlisted plugin endpoints when the project scope permits them, including the Jenkins branch trigger endpoint for build jenkins-trigger.

Provider-specific caveats

• Prefer stable, structured CLI output that downstream agents can parse reliably.
• Distinguish read actions and write actions explicitly.
• For write failures, return explicit and actionable failure details; do not swallow errors.

Review behavior

• During code review, if no high-confidence, actionable, non-trivial issues are found, return a clean result instead of proposing or submitting comments, and use pr approve when the task is to submit the review result.

Quick reference — common operations

Use these directly without reading supporting files. BIN = the resolved launcher path for this session, not the literal ${BITBUCKET_SKILL_DIR} placeholder token.

Task	Command
Trigger build (simplified)	BIN build trigger --repo <slug> --branch <name> [--project <KEY>]
Trigger build (explicit)	BIN build jenkins-trigger --project <KEY> --repo <slug> --branch refs/heads/<name>
List repos in a project	BIN repo list --project <KEY>
Search repos by name	BIN repo search --name <name>
List open PRs (project)	BIN pr list --project <KEY> --state OPEN --draft false
List merged PRs (date)	BIN pr list --project <KEY> --state MERGED --after YYYY-MM-DD
Get single PR	BIN pr get --project <KEY> --repo <slug> --id <ID>
Create branch	BIN branch create --project <KEY> --repo <slug> --name <branch> --start-point <ref>
Read file content	BIN repo content --project <KEY> --repo <slug> --path <path> [--at <ref>]

Notes on build trigger:

• --branch accepts short names like dev (auto-prefixed to refs/heads/dev) or full refs.
• --project is optional; when omitted, auto-resolved from repo slug via search. If multiple repos share the same slug across projects, specify --project explicitly.
• For requests to trigger a specific repository branch build, default to BIN build trigger --repo <slug> --branch <name> and do not run repo search just to discover the project key.
• Only fall back to BIN build jenkins-trigger ... when the user already provided --project, build trigger reports that the same slug exists in multiple projects, or the user explicitly asks for full refs or explicit control.
• Protected branches (main/master/prod/production) require --confirm-production true.

Capability Domain

Domain:

• repo

Provides:

• repo.config.get
• repo.config.set
• repo.repo.list
• repo.repo.search
• repo.repo.get
• repo.repo.content
• repo.repo.default-branch.get
• repo.branch.list
• repo.branch.create
• repo.pr.list
• repo.pr.get
• repo.pr.changes
• repo.pr.diff
• repo.pr.activities
• repo.pr.create
• repo.pr.update
• repo.pr.comment
• repo.pr.review-comment
• repo.pr.approve
• repo.commit.list
• repo.commit.get
• repo.commit.changes
• repo.commit.pull-requests
• repo.repo.required-reviewers
• repo.pr.linked-work-items
• repo.issue.linked-commits-via-repo
• project-scoped pull request aggregation
• provider-specific workflow helpers

Config check:

• bitbucket config get

Config check

Run bitbucket config get when configuration state is unknown or before the first provider-scoped task in a new session.

Supporting files

• Read references/commands.md for command families and packaged launcher forms.
• Read references/usage.md for execution policy, aggregation rules, and read/write behavior.
• Follow references/usage.md finding classification and routing rules before submitting PR review feedback.
• Read examples/common-workflows.md for end-to-end examples.