---
name: Bkt Skill
slug: bkt-skill
category: Automation
description: Bkt Skill installs, lists, previews, updates, and publishes agent skills from Bitbucket repositories or local directories. Use it to manage skill packages for Claude Code and other supported agents.
github: "https://github.com/avivsinai/bitbucket-cli/tree/master/skills/bkt/rules"
language: Go
stars: 200
forks: 44
install: "npx degit https://github.com/avivsinai/bitbucket-cli/tree/master/skills/bkt/rules ~/.claude/skills/rules"
installs_to: ~/.claude/skills/rules
source_path: skills/bkt/rules/skill.md
collection_size: 2
category_size: 1956
collection_url: "https://dirskills.com/collections/avivsinai/bitbucket-cli"
added: 2026-09-05T05:30:53.115Z
last_synced: 2026-09-05T05:30:53.115Z
canonical_url: "https://dirskills.com/skills/bkt-skill"
---

# Bkt Skill

Bkt Skill installs, lists, previews, updates, and publishes agent skills from Bitbucket repositories or local directories. Use it to manage skill packages for Claude Code and other supported agents.

**Install:**

```bash
npx degit https://github.com/avivsinai/bitbucket-cli/tree/master/skills/bkt/rules ~/.claude/skills/rules
```

## README

<!-- auto-generated by cmd/docgen — do not edit -->

# 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

```bash
# 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

| Subcommand | Description | Key Flags |
|---|---|---|
| [install](#bkt-skill-install) | Install agent skills from a Bitbucket repository | `--agent`, `--all`, `--allow-hidden-dirs`, `--dir` |
| [list](#bkt-skill-list) | List installed skills | `--agent`, `--dir`, `--scope` |
| [preview](#bkt-skill-preview) | Preview a skill from a Bitbucket repository | `--allow-hidden-dirs` |
| [publish](#bkt-skill-publish) | Validate skills and tag a release | `--dry-run`, `--fix`, `--message`, `--tag` |
| [search](#bkt-skill-search) | Search for skills in Bitbucket Cloud code | `--limit`, `--workspace` |
| [update](#bkt-skill-update) | Update installed skills to their latest versions | `--all`, `--dir`, `--dry-run`, `--force` |

## 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

| Flag | Short | Description |
|---|---|---|
| `--agent` |  | Target agent (see supported values above) |
| `--all` |  | Install all skills in the repository |
| `--allow-hidden-dirs` |  | Include skills in hidden directories (e.g. .claude/skills/, .agents/skills/) |
| `--dir` |  | Install to a custom directory (overrides --agent and --scope) |
| `--force` | `-f` | Overwrite existing skills without prompting |
| `--from-local` |  | Treat the argument as a local directory path instead of a repository |
| `--pin` |  | Pin to a specific tag, branch, or commit SHA |
| `--scope` |  | Installation scope: project or user |
| `--upstream` |  | Install from the upstream source when a re-published skill is detected |

### Inherited Flags

| Flag | Short | Description |
|---|---|---|
| `--context` | `-c` | Active Bitbucket context name |
| `--format` |  | Output format: json or yaml (alias for --json/--yaml) |
| `--jq` |  | Apply a jq expression to JSON output (requires --json or --format json) |
| `--json` |  | Output in JSON format when supported |
| `--template` |  | Render output using Go templates |
| `--yaml` |  | Output in YAML format when supported |

### Examples

```bash
# 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

| Flag | Short | Description |
|---|---|---|
| `--agent` |  | Filter by target agent (see `bkt skill install --help` for values) |
| `--dir` |  | Scan a custom directory for installed skills |
| `--scope` |  | Filter by installation scope: project or user |

### Inherited Flags

| Flag | Short | Description |
|---|---|---|
| `--context` | `-c` | Active Bitbucket context name |
| `--format` |  | Output format: json or yaml (alias for --json/--yaml) |
| `--jq` |  | Apply a jq expression to JSON output (requires --json or --format json) |
| `--json` |  | Output in JSON format when supported |
| `--template` |  | Render output using Go templates |
| `--yaml` |  | Output in YAML format when supported |

### Examples

```bash
# 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

| Flag | Short | Description |
|---|---|---|
| `--allow-hidden-dirs` |  | Include skills in hidden directories (e.g. .claude/skills/, .agents/skills/) |

### Inherited Flags

| Flag | Short | Description |
|---|---|---|
| `--context` | `-c` | Active Bitbucket context name |
| `--format` |  | Output format: json or yaml (alias for --json/--yaml) |
| `--jq` |  | Apply a jq expression to JSON output (requires --json or --format json) |
| `--json` |  | Output in JSON format when supported |
| `--template` |  | Render output using Go templates |
| `--yaml` |  | Output in YAML format when supported |

### Examples

```bash
# 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

| Flag | Short | Description |
|---|---|---|
| `--dry-run` |  | Validate without tagging |
| `--fix` |  | Strip committed install metadata without tagging |
| `--message` |  | Annotation for the tag (defaults to the tag name) |
| `--tag` |  | Tag the current commit with this version (e.g. v1.2.0) |

### Inherited Flags

| Flag | Short | Description |
|---|---|---|
| `--context` | `-c` | Active Bitbucket context name |
| `--format` |  | Output format: json or yaml (alias for --json/--yaml) |
| `--jq` |  | Apply a jq expression to JSON output (requires --json or --format json) |
| `--json` |  | Output in JSON format when supported |
| `--template` |  | Render output using Go templates |
| `--yaml` |  | Output in YAML format when supported |

### Examples

```bash
# 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

| Flag | Short | Description |
|---|---|---|
| `--limit` | `-L` | Maximum matches to return |
| `--workspace` |  | Bitbucket Cloud workspace (defaults to context workspace) |

### Inherited Flags

| Flag | Short | Description |
|---|---|---|
| `--context` | `-c` | Active Bitbucket context name |
| `--format` |  | Output format: json or yaml (alias for --json/--yaml) |
| `--jq` |  | Apply a jq expression to JSON output (requires --json or --format json) |
| `--json` |  | Output in JSON format when supported |
| `--template` |  | Render output using Go templates |
| `--yaml` |  | Output in YAML format when supported |

### Examples

```bash
# 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

| Flag | Short | Description |
|---|---|---|
| `--all` |  | Update all skills without prompting |
| `--dir` |  | Scan a custom directory for installed skills |
| `--dry-run` |  | Report available updates without modifying files |
| `--force` |  | Re-download even if already up to date |
| `--unpin` |  | Clear pinned version and include pinned skills in update |

### Inherited Flags

| Flag | Short | Description |
|---|---|---|
| `--context` | `-c` | Active Bitbucket context name |
| `--format` |  | Output format: json or yaml (alias for --json/--yaml) |
| `--jq` |  | Apply a jq expression to JSON output (requires --json or --format json) |
| `--json` |  | Output in JSON format when supported |
| `--template` |  | Render output using Go templates |
| `--yaml` |  | Output in YAML format when supported |

### Examples

```bash
# 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
```