bkt skill

Install and manage agent skills from Bitbucket repositories.

Skills are directories containing a SKILL.md file that teach AI coding agents (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and many more) how to perform a task. This command group mirrors "gh skill" so the same workflow works for skills hosted on Bitbucket Cloud and Bitbucket Data Center. Repositories are addressed as WORKSPACE/REPO (Cloud) or PROJECT/REPO (Data Center) and accessed with the credentials of the active context.

See https://agentskills.io/specification for the skill format.

bkt skill <command> [flags]

Examples

# Install a skill from a Bitbucket repository
  bkt skill install myteam/agent-skills code-review

  # List installed skills
  bkt skill list

  # Preview a skill before installing
  bkt skill preview myteam/agent-skills code-review

  # Update all installed skills
  bkt skill update --all

Subcommands

bkt skill install

Install agent skills from a Bitbucket repository or local directory into your local environment. Skills are placed in a host-specific directory at either project scope (inside the current git repository) or user scope (in your home directory, available everywhere).

Supported --agent values:

• GitHub Copilot (github-copilot)
• Claude Code (claude-code)
• Cursor (cursor)
• Codex (codex)
• Gemini CLI (gemini-cli)
• Antigravity (antigravity)
• Antigravity CLI (antigravity-cli)
• Antigravity 2.0 (antigravity2.0)
• AdaL (adal)
• Amp (amp)
• Augment (augment)
• IBM Bob (bob)
• Cline (cline)
• CodeBuddy (codebuddy)
• Command Code (command-code)
• Continue (continue)
• Cortex Code (cortex)
• Crush (crush)
• Deep Agents (deepagents)
• Devin (devin)
• Droid (droid)
• Firebender (firebender)
• Goose (goose)
• Grok (grok)
• iFlow CLI (iflow-cli)
• Junie (junie)
• Kilo Code (kilo)
• Kimi Code CLI (kimi-cli)
• Kiro CLI (kiro-cli)
• Kode (kode)
• MCPJam (mcpjam)
• Mistral Vibe (mistral-vibe)
• Mux (mux)
• Neovate (neovate)
• OpenClaw (openclaw)
• OpenCode (opencode)
• OpenHands (openhands)
• Pi (pi)
• Pochi (pochi)
• Qoder (qoder)
• Qwen Code (qwen-code)
• Replit (replit)
• Roo Code (roo)
• Trae (trae)
• Trae CN (trae-cn)
• Universal (universal)
• Warp (warp)
• Zencoder (zencoder)

Use --agent and --scope to control placement, or --dir for a custom directory. The default scope is "project" and the default agent is "universal", which installs into the shared .agents/skills directory read by GitHub Copilot, Cursor, Codex, Gemini CLI, Antigravity, Amp, Cline, OpenCode, Warp and others. Agents that resolve to the same destination share one copy.

The first argument is a Bitbucket repository: WORKSPACE/REPO on Bitbucket Cloud, PROJECT/REPO on Bitbucket Data Center, or a full repository URL. The active context (or --context) supplies the host and credentials. Use --from-local to install from a local directory instead; files are copied (not symlinked) with local-path tracking metadata injected into frontmatter.

Skills are discovered using the skills//SKILL.md convention from the Agent Skills specification (https://agentskills.io/specification), including namespaced skills/{author}//SKILL.md, plugins//skills//SKILL.md, root-level */SKILL.md, and a skills/ directory nested under a prefix.

The skill argument can be a name, a namespaced name (author/skill), or an exact path within the repository (skills/author/skill, packages/agent-skills/code-review, or any .../SKILL.md path). Passing an exact path skips the full repository listing, which is faster on large repositories.

When a skill name is given without a version, the newest tag is used, falling back to the default branch when the repository has no tags. To pin a version, append @VERSION to the skill name or use --pin; the version is resolved as a tag, branch, or commit SHA.

Installed skills carry source metadata (metadata.bitbucket-*) in their SKILL.md frontmatter so "bkt skill update" can detect changes.

Use --all to install every discovered skill. Without a skill name or --all, the available skills are listed (tab-separated when piped) so you can browse or grep them before re-running with a specific skill.

Alias: add

Usage

bkt skill install <repository> [<skill[@version]>] [flags]

Flags

Inherited Flags

Examples

# List the skills available in a repository
  bkt skill install myteam/agent-skills

  # Install a specific skill into .agents/skills of the current repository
  bkt skill install myteam/agent-skills code-review

  # Install all skills from a repository
  bkt skill install myteam/agent-skills --all

  # Install a specific version
  bkt skill install myteam/agent-skills code-review@v1.2.0

  # Install by exact path (skips the full repository listing)
  bkt skill install myteam/agent-skills skills/monalisa/code-review

  # Install for Claude Code at user scope
  bkt skill install myteam/agent-skills code-review --agent claude-code --scope user

  # Install from a Data Center repository by project key
  bkt skill install PROJ/agent-skills code-review

  # Install from a local directory
  bkt skill install ./my-skills-repo code-review --from-local

  # Include skills kept in hidden directories such as .claude/skills/
  bkt skill install myteam/agent-skills --allow-hidden-dirs

bkt skill list

List installed agent skills across known agent host directories.

By default, scans all supported agent hosts in both project and user scope. Use --agent to scan one host, --scope to scan only project or user scope, or --dir to scan a custom skills directory.

Project-scope skills are discovered relative to the current git repository root. User-scope skills are discovered relative to your home directory. Skills authored in the current repository's skills/ directory are listed as published. Skills installed by other tools (for example gh) are listed with the source they record.

Alias: ls

Usage

bkt skill list [flags]

Flags

Inherited Flags

Examples

# List all installed skills
  bkt skill list

  # List skills installed for Claude Code
  bkt skill list --agent claude-code

  # List user-scope skills
  bkt skill list --scope user

  # List skills as JSON
  bkt skill list --json

bkt skill preview

Show a skill's files and SKILL.md content in the terminal without installing anything. The output goes through the configured pager when stdout is a terminal.

A file tree is shown first, followed by SKILL.md and the skill's other files (up to 20 files or 512 KiB).

When run with only a repository argument, the available skills are listed.

The skill argument can be a name, a namespaced name (author/skill), or an exact path within the repository (skills/author/skill, packages/agent-skills/code-review, or any .../SKILL.md path).

To preview a specific version, append @VERSION to the skill name. The version is resolved as a branch, tag, or commit SHA.

Alias: show

Usage

bkt skill preview <repository> [<skill[@version]>] [flags]

Flags

Inherited Flags

Examples

# Preview a specific skill
  bkt skill preview myteam/agent-skills code-review

  # Preview a skill at a specific version
  bkt skill preview myteam/agent-skills code-review@v1.2.0

  # Preview exactly what an install wrote, by commit SHA
  bkt skill preview myteam/agent-skills code-review@abc123def456

  # Preview from a non-standard nested path
  bkt skill preview myteam/skills-repo packages/agent-skills/code-review

  # List the skills available in a repository
  bkt skill preview myteam/agent-skills

bkt skill publish

Validate a repository's skills against the Agent Skills specification and, with --tag, mark the current commit as a released version.

Skills are discovered with the same conventions as install: skills//SKILL.md, skills/{author}//SKILL.md, plugins//skills//SKILL.md, root-level */SKILL.md, and a skills/ directory nested under a prefix. Skills in hidden directories are ignored: those are copies installed by an agent, not the repository's own work.

Validation checks:

• the skill name follows the agentskills.io naming rules
• the skill name matches its directory name
• the required frontmatter fields (name, description) are present
• allowed-tools is a space-delimited string, not a list
• no install metadata (metadata.bitbucket-, metadata.github-, local-path) is committed, since that records where a copy came from

Recommendations are reported as warnings: a license field, a description under 1024 characters, and a body under 500 lines.

Use --dry-run to validate without tagging, and --fix to strip install metadata from the committed files so you can review and commit the result.

Bitbucket has no releases, so publishing a version means creating a tag on the current commit. "bkt skill install" resolves an unversioned request to the newest tag, so tagging is what makes a version installable.

Usage

bkt skill publish [<directory>] [flags]

Flags

Inherited Flags

Examples

# Validate the skills in the current repository
  bkt skill publish --dry-run

  # Strip committed install metadata, then review the changes
  bkt skill publish --fix

  # Validate and tag the current commit as v1.2.0
  bkt skill publish --tag v1.2.0

  # Validate a repository checked out elsewhere
  bkt skill publish ./agent-skills --dry-run

bkt skill search

Search for skill files across repositories in a Bitbucket Cloud workspace.

The query uses Bitbucket Cloud code-search syntax. Scope it further with terms such as repo:agent-skills or path:skills. The workspace comes from --workspace or the active context. Results are restricted to SKILL.md files. Bitbucket Data Center is not supported because it has no public workspace code-search API.

Note: Atlassian has announced that the Cloud code-search REST endpoint will be deprecated on November 1, 2026.

Usage

bkt skill search <query> [flags]

Flags

Inherited Flags

Examples

# Search the active context's workspace
  bkt skill search "code review"

  # Search one repository and emit structured output
  bkt skill search "review repo:agent-skills" --workspace myteam --json

bkt skill update

Check installed skills for updates by comparing the commit recorded in each SKILL.md frontmatter (metadata.bitbucket-commit) against the latest commit that touched the skill in its source repository, and reinstall the ones that changed.

Scans every known agent host directory in both project and user scope, or a single directory with --dir. Without arguments, checks all installed skills; with skill names, checks only those.

Pinned skills (installed with --pin or @version) are skipped with a notice. Use --unpin to clear the pin and include them in the update.

Skills without Bitbucket metadata (installed manually or by another tool) are prompted for their source repository in interactive mode. With --all or in non-interactive mode they are skipped with a notice. Skills installed by gh are listed with a reminder to update them with gh.

With --force, skills are re-downloaded even when already up to date. This overwrites locally modified files with their original content and removes extra files added locally.

In interactive mode, the available updates are shown and confirmed before proceeding. With --all, updates are applied without prompting. With --dry-run, updates are reported without modifying any files.

Usage

bkt skill update [<skill>...] [flags]

Flags

Inherited Flags

Examples

# Check and update all skills interactively
  bkt skill update

  # Update specific skills
  bkt skill update code-review git-commit

  # Update all without prompting
  bkt skill update --all

  # Re-download all skills (restore locally modified files)
  bkt skill update --force --all

  # Check for updates without applying
  bkt skill update --dry-run

  # Unpin skills and update them to latest
  bkt skill update --unpin