Skip to content

cloudthinker-ai/CloudSkills / skills/connections/bitbucket

bitbucket

Unverified

REQUIRED helper functions (never raw curl), workspace/repo_slug patterns, suggestion block syntax for code review

Bitbucket CLI Skill

Execute Bitbucket helper functions with proper authentication via OAuth token.

You must source the helpers before use:

source ./_skills/connections/bitbucket/bitbucket/scripts/bitbucket_helpers.sh

CLI Tips

NEVER USE RAW CURL OR DIRECT API CALLS

DO NOT write raw curl/HTTP requests like:

# ❌ WRONG - Never do this
curl -s -H "Authorization: Bearer ${BITBUCKET_TOKEN}" "https://api.bitbucket.org/2.0/..."

ALWAYS use the provided helper functions:

# βœ… CORRECT - Use helper functions
bitbucket_test                              # Test connection
bitbucket_user                              # Get current user
bitbucket_pr myworkspace myrepo 123         # Get PR details

The helper functions handle authentication, error handling, retries, and output formatting automatically.

CRITICAL: Workspace and Repo Slug Parameters

ALL commands require explicit workspace and repo_slug as parameters.

bitbucket_pr myworkspace myrepo 123        # Get PR details
bitbucket_pr_diff myworkspace myrepo 123   # Get PR diff

Code Review Helper Functions (Bitbucket)

Inline comment with suggestion block:

bitbucket_create_pr_comment myworkspace myrepo 123 "file.py" 45 'Comment text

```suggestion
fixed code
```
'
  • Use single quotes to preserve backticks literally - NO escaping needed

Discussion comment (not line-specific):

bitbucket_create_pr_discussion myworkspace myrepo 123 'Overall review summary'

Suggestion Block Syntax (CRITICAL)

βœ… CORRECT - Single quotes preserve backticks:

bitbucket_create_pr_comment myworkspace myrepo 123 "src/app.py" 45 'πŸ”΄ CRITICAL: Issue

```suggestion
if not input:
    raise ValueError("Required")
```
'

❌ WRONG - Escaped backticks break rendering:

bitbucket_create_pr_comment myworkspace myrepo 123 "src/app.py" 45 "\`\`\`suggestion
code
\`\`\`"

Key rules:

  • Use single quotes to wrap comment body containing markdown
  • Backticks inside single quotes are literal - write them normally
  • NEVER escape backticks with backslashes (\`) - this breaks Bitbucket's markdown parser
  • Triple backticks for suggestion blocks must be literal: ```suggestion

Essential Read Commands

Connection and user info:

bitbucket_test                              # Test connection
bitbucket_user                              # Get current user info
bitbucket_workspaces                        # List accessible workspaces

Repository info:

bitbucket_repo myworkspace myrepo           # Get repository details
bitbucket_repos myworkspace                 # List repositories in workspace
bitbucket_branches myworkspace myrepo       # List branches

Pull request info:

bitbucket_pr myworkspace myrepo 123                # Get PR details
bitbucket_pr_diff myworkspace myrepo 123           # Get PR diff
bitbucket_pr_comments myworkspace myrepo 123       # Get PR comments

Pipeline info:

bitbucket_pipeline myworkspace myrepo PIPELINE_UUID           # Get pipeline details
bitbucket_pipeline_steps myworkspace myrepo PIPELINE_UUID     # Get pipeline steps

Supported Parameters Reference

bitbucket_pr - Get pull request details

Required parameters:

  1. workspace : Workspace slug
  2. repo_slug : Repository slug
  3. pr_id : Pull request ID

Example:

bitbucket_pr myworkspace myrepo 123

bitbucket_pr_diff - Get pull request diff

Required parameters:

  1. workspace : Workspace slug
  2. repo_slug : Repository slug
  3. pr_id : Pull request ID

Returns: Unified diff text

bitbucket_pr_comments - Get PR comments

Required parameters:

  1. workspace : Workspace slug
  2. repo_slug : Repository slug
  3. pr_id : Pull request ID

Returns: JSON array of comment objects

bitbucket_repos - List repositories

Required parameters:

  1. workspace : Workspace slug

Optional parameters:

  • Second param: Results per page (default: 25)

Example:

bitbucket_repos myworkspace 50  # Get up to 50 repos

Write Commands (Code Review)

bitbucket_create_pr_comment - Inline code comment

Required parameters:

  1. workspace : Workspace slug
  2. repo_slug : Repository slug
  3. pr_id : Pull request ID
  4. file_path : Path to file (e.g., 'src/app.py')
  5. line_number : Line number on NEW side of diff
  6. body : Comment text (use single quotes for markdown)

Example with suggestion:

bitbucket_create_pr_comment myworkspace myrepo 123 "src/auth.py" 45 'Add input validation

```suggestion
if not validate_input(data):
    raise ValueError("Invalid input")
```
'

bitbucket_create_pr_discussion - General PR comment

Required parameters:

  1. workspace : Workspace slug
  2. repo_slug : Repository slug
  3. pr_id : Pull request ID
  4. body : Comment text

Use this for:

  • Overall review summaries
  • General feedback that doesn't apply to specific lines

Example:

bitbucket_create_pr_discussion myworkspace myrepo 123 'Code Review Summary

Looks good overall:
- 3 files reviewed
- 2 inline comments posted
- Ready for merge'

bitbucket_update_comment - Update existing comment

Required parameters:

  1. workspace : Workspace slug
  2. repo_slug : Repository slug
  3. pr_id : Pull request ID
  4. comment_id : Comment ID to update
  5. body : New comment text

bitbucket_delete_comment - Delete comment

Required parameters:

  1. workspace : Workspace slug
  2. repo_slug : Repository slug
  3. pr_id : Pull request ID
  4. comment_id : Comment ID to delete

Key Rules

  1. ALWAYS use helper functions for code review inline comments - Use bitbucket_create_pr_comment
  2. Always specify workspace and repo_slug - Every command needs them
  3. For general operations: Use helper functions (list, view, etc.)
  4. Write operations: All require user approval
  5. Suggestion blocks: Must use helper functions with single quotes
  6. Multi-repo: Use explicit workspace/repo for each command:
    bitbucket_pr workspace1 frontend-repo 45
    bitbucket_pr workspace1 backend-repo 67
    

Errors

ProblemSolution
"401 Unauthorized"Token expired, refresh OAuth token
"404 Not Found"Check workspace/repo_slug spelling
"Rate limit exceeded"Helper auto-retries, wait a few seconds
"line not in diff"Use bitbucket_create_pr_discussion instead
Empty responseCheck if PR/resource exists

Critical Operations

⚠️ NEVER do these without explicit user instruction:

  • bitbucket_delete_comment - Only on explicit request
  • Any operation that modifies PR state - Only on explicit request

API Notes

  • Bitbucket Cloud API 2.0 is used
  • All responses are paginated (helper handles this)
  • Rate limiting: 1000 requests/hour per user
  • Token expiration: OAuth tokens expire, helper shows warning

Output Format

Present results as a structured report:

Bitbucket Report
════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≀50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

  1. NEVER assume resource names β€” always discover via CLI/API in Phase 1 before referencing in Phase 2.
  2. NEVER fabricate metric names or dimensions β€” verify against the service documentation or --help output.
  3. NEVER mix CLI commands between service versions β€” confirm which version/API you are targeting.
  4. ALWAYS use the discovery β†’ verify β†’ analyze chain β€” every resource referenced must have been discovered first.
  5. ALWAYS handle empty results gracefully β€” an empty response is valid data, not an error to retry.

Counter-Rationalizations

ShortcutCounterWhy
"I'll skip discovery and check known resources"Always run Phase 1 discovery firstResource names change, new resources appear β€” assumed names cause errors
"The user only asked for a quick check"Follow the full discovery β†’ analysis flowQuick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"Audit configuration explicitlyDefaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"Always check relevant metrics when availableAPI/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"Try the command and report the actual errorAssumed permission failures prevent useful investigation; actual errors are informative
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall