ContextQMD
Back to Bmad Method

Native Skills Migration Checklist

tools/docs/native-skills-migration-checklist.md

6.6.017.4 KB
Original Source

Native Skills Migration Checklist

Branch: refactor/all-is-skills

Scope: migrate the BMAD-supported platforms that fully support the Agent Skills standard from legacy installer outputs to native skills output.

Current branch status:

  • Claude Code has already been moved to .claude/skills
  • Codex CLI has already been moved to .agents/skills

This checklist now includes those completed platforms plus the remaining full-support platforms.

Claude Code

Support assumption: full Agent Skills support. BMAD has already migrated from .claude/commands to .claude/skills.

Install: npm install -g @anthropic-ai/claude-code or brew install claude-code

  • Confirm current implementation still matches Claude Code skills expectations
  • Confirm legacy cleanup for .claude/commands
  • Test fresh install
  • Test reinstall/upgrade from legacy command output
  • Confirm ancestor conflict protection because Claude Code inherits skills from parent directories and ancestor_conflict_check: true is set in platform-codes.yaml
  • Implement/extend automated tests as needed

Codex CLI

Support assumption: full Agent Skills support. BMAD has already migrated from .codex/prompts to .agents/skills.

Install: npm install -g @openai/codex

  • Confirm current implementation still matches Codex CLI skills expectations
  • Confirm legacy cleanup for project and global .codex/prompts
  • Test fresh install
  • Test reinstall/upgrade from legacy prompt output
  • Confirm ancestor conflict protection because Codex inherits parent-directory .agents/skills
  • Implement/extend automated tests as needed

Cursor

Support assumption: full Agent Skills support. BMAD currently installs legacy command files to .cursor/commands; target should move to a native skills directory.

  • Confirm current Cursor skills path and that BMAD should target .cursor/skills
  • Implement installer migration to native skills output
  • Add legacy cleanup for .cursor/commands
  • Test fresh install
  • Test reinstall/upgrade from legacy command output
  • Confirm no ancestor conflict protection is needed because a child workspace surfaced child .cursor/skills entries but not a parent-only skill during manual verification
  • Implement/extend automated tests
  • Commit

Windsurf

Support assumption: full Agent Skills support. Windsurf docs confirm workspace skills at .windsurf/skills and global skills at ~/.codeium/windsurf/skills. BMAD has now migrated from .windsurf/workflows to .windsurf/skills. Manual verification also confirmed that Windsurf custom skills are triggered via @skill-name, not slash commands.

  • Confirm Windsurf native skills directory as .windsurf/skills
  • Implement installer migration to native skills output
  • Add legacy cleanup for .windsurf/workflows
  • Test fresh install
  • Test reinstall/upgrade from legacy workflow output
  • Confirm no ancestor conflict protection is needed because manual Windsurf verification showed child-local @ skills loaded while a parent-only skill was not inherited
  • Implement/extend automated tests

Cline

Support assumption: full Agent Skills support. Cline docs confirm workspace skills at .cline/skills/<skill-name>/SKILL.md and global skills at ~/.cline/skills/. BMAD has now migrated from .clinerules/workflows to .cline/skills.

Install: VS Code extension saoudrizwan.claude-dev — search "Cline" in Extensions or code --install-extension saoudrizwan.claude-dev

  • Confirm current Cline skills path is .cline/skills/{skill-name}/SKILL.md with YAML frontmatter (name + description)
  • Implement installer migration to native skills output
  • Add legacy cleanup for .clinerules/workflows
  • Test fresh install — 43 skills installed to .cline/skills/
  • Test reinstall/upgrade from legacy workflow output
  • Confirm no ancestor conflict protection is needed because Cline only scans workspace-local .cline/skills/ and global ~/.cline/skills/, with no ancestor directory inheritance
  • Implement/extend automated tests — 9 assertions in test suite 18
  • Commit

Google Antigravity

Support assumption: full Agent Skills support. Antigravity docs confirm workspace skills at .agent/skills/<skill-folder>/ and global skills at ~/.gemini/antigravity/skills/<skill-folder>/. BMAD has now migrated from .agent/workflows to .agent/skills.

  • Confirm Antigravity native skills path and project/global precedence
  • Implement installer migration to native skills output
  • Add legacy cleanup for .agent/workflows
  • Test fresh install
  • Test reinstall/upgrade from legacy workflow output
  • Confirm no ancestor conflict protection is needed because manual Antigravity verification in /tmp/antigravity-ancestor-repro/parent/child showed only the child-local child-only skill, with no inherited parent .agent/skills entry
  • Implement/extend automated tests

Auggie

Support assumption: full Agent Skills support. BMAD currently installs commands to .augment/commands; target should move to .augment/skills.

  • Confirm Auggie native skills path and compatibility loading from .claude/skills and .agents/skills via Augment docs plus local auggie --print repros
  • Implement installer migration to native skills output
  • Add legacy cleanup for .augment/commands
  • Test fresh install
  • Test reinstall/upgrade from legacy command output
  • Confirm no ancestor conflict protection is needed because local auggie --workspace-root repro showed child-local .augment/skills loading child-only but not parent parent-only
  • Implement/extend automated tests
  • Commit

CodeBuddy

Support assumption: full Agent Skills support. CodeBuddy docs confirm workspace skills at .codebuddy/skills/<skill-name>/SKILL.md and global skills at ~/.codebuddy/commands/. BMAD has now migrated from .codebuddy/commands to .codebuddy/skills.

Install: Download Tencent CodeBuddy IDE or install as VS Code extension CodebuddyAI.codebuddy-ai

  • Confirm CodeBuddy native skills path is .codebuddy/skills/{skill-name}/SKILL.md with YAML frontmatter (name + description) — per docs, not IDE-verified
  • Implement installer migration to native skills output
  • Add legacy cleanup for .codebuddy/commands
  • Test fresh install — 43 skills installed to .codebuddy/skills/ (installer output only)
  • Test reinstall/upgrade from legacy command output
  • NEEDS MANUAL IDE VERIFICATION — requires Tencent Cloud account; confirm skills appear in UI and test ancestor inheritance
  • Implement/extend automated tests — 9 assertions in test suite 19
  • Commit

Crush

Support assumption: full Agent Skills support. Crush scans project-local .crush/skills/ exclusively (GitHub issue #2072 confirms this and requests adding ~/.agents/skills/). BMAD has now migrated from .crush/commands to .crush/skills.

Install: brew install charmbracelet/tap/crush (macOS/Linux) or winget install charmbracelet.crush (Windows)

  • Confirm Crush project-local skills path is .crush/skills/{skill-name}/SKILL.md — per GitHub issue #2072 confirming .crush/skills/ is the only scan path
  • Implement installer migration to native skills output
  • Add legacy cleanup for .crush/commands
  • Test fresh install — 43 skills installed to .crush/skills/
  • Test reinstall/upgrade from legacy command output
  • Confirm no ancestor conflict protection is needed because Crush only scans project-local .crush/skills/, no ancestor inheritance
  • Manual CLI verification — crush run lists all 10 skills and successfully triggers bmad-help
  • Implement/extend automated tests — 9 assertions in test suite 20
  • Commit

Kiro

Support assumption: full Agent Skills support. Kiro docs confirm project skills at .kiro/skills/<skill-name>/SKILL.md and describe steering as a separate rules mechanism, not a required compatibility layer. BMAD has now migrated from .kiro/steering to .kiro/skills. Manual app verification also confirmed that Kiro can surface skills in Slash when the relevant UI setting is enabled, and that it does not inherit ancestor .kiro/skills directories.

  • Confirm Kiro skills path and verify BMAD should stop writing steering artifacts for this migration
  • Implement installer migration to native skills output
  • Add legacy cleanup for .kiro/steering
  • Test fresh install
  • Test reinstall/upgrade from legacy steering output
  • Confirm no ancestor conflict protection is needed because manual Kiro verification showed Slash-visible skills from the current workspace only, with no ancestor .kiro/skills inheritance
  • Implement/extend automated tests

OpenCode

Support assumption: full Agent Skills support. BMAD currently splits output between .opencode/agents and .opencode/commands; target should consolidate to .opencode/skills.

  • Confirm OpenCode native skills path and compatibility loading from .claude/skills and .agents/skills in OpenCode docs and with local opencode run repros
  • Implement installer migration from multi-target legacy output to single native skills target
  • Add legacy cleanup for .opencode/agents, .opencode/commands, .opencode/agent, and .opencode/command
  • Test fresh install
  • Test reinstall/upgrade from split legacy output
  • Confirm ancestor conflict protection is required because local opencode run repros loaded both child-local child-only and ancestor parent-only, matching the docs that project-local skill discovery walks upward to the git worktree
  • Implement/extend automated tests
  • Commit

Roo Code

Support assumption: full Agent Skills support. BMAD currently installs commands to .roo/commands; target should move to .roo/skills or the correct mode-aware skill directories.

Install: VS Code extension RooVeterinaryInc.roo-cline — search "Roo Code" in Extensions or code --install-extension RooVeterinaryInc.roo-cline

  • Confirm Roo native skills path is .roo/skills/{skill-name}/SKILL.md with name frontmatter matching directory exactly (lowercase, alphanumeric + hyphens only)
  • Implement installer migration to native skills output
  • Add legacy cleanup for .roo/commands
  • Test fresh install — 43 skills installed, verified in Roo Code v3.51
  • Test reinstall/upgrade from legacy command output
  • Confirm no ancestor conflict protection is needed because manual Roo Code v3.51 verification showed child-local child-only skill loaded while parent-only skill was not inherited
  • Implement/extend automated tests — 7 assertions in test suite 13
  • Commit

Trae

Support assumption: full Agent Skills support. Trae docs confirm workspace skills at .trae/skills/<skill-name>/SKILL.md. BMAD has now migrated from .trae/rules to .trae/skills.

Install: Download standalone IDE (macOS/Windows/Linux) or winget install -e --id ByteDance.Trae

  • Confirm Trae native skills path is .trae/skills/{skill-name}/SKILL.md — per official docs
  • Implement installer migration to native skills output
  • Add legacy cleanup for .trae/rules
  • Test fresh install — 43 skills installed to .trae/skills/
  • Test reinstall/upgrade from legacy rules output
  • Confirm no ancestor conflict protection is needed — Trae docs describe project-local .trae/skills/ only
  • NEEDS MANUAL IDE VERIFICATION — download Trae IDE and confirm skills appear in UI
  • Implement/extend automated tests — 9 assertions in test suite 21
  • Commit

GitHub Copilot

Support assumption: full Agent Skills support. BMAD currently uses a custom installer that generates .github/agents, .github/prompts, and .github/copilot-instructions.md; target should move to .github/skills.

Install: VS Code extension GitHub.copilot — search "GitHub Copilot" in Extensions or code --install-extension GitHub.copilot

  • Confirm GitHub Copilot native skills path is .github/skills/{skill-name}/SKILL.md — also reads .claude/skills/ automatically
  • Design the migration away from the custom prompt/agent installer model — replaced 699-line custom installer with config-driven skill_format: true
  • Implement native skills output, ideally with shared config-driven code where practical
  • Add legacy cleanup for .github/agents, .github/prompts, and BMAD markers in copilot-instructions.md
  • Test fresh install — 43 skills installed to .github/skills/
  • Test reinstall/upgrade from legacy custom installer output — legacy dirs removed, BMAD markers stripped, user content preserved
  • Confirm no ancestor conflict protection is needed because manual Copilot verification showed child-local child-only skill loaded while parent-only skill was not inherited
  • Implement/extend automated tests — 11 assertions in test suite 17 including marker cleanup
  • Commit

KiloCoder

Install: VS Code extension kilocode.kilo-code — search "Kilo Code" in Extensions or code --install-extension kilocode.kilo-code

  • Confirm KiloCoder native skills path — .kilocode/skills
  • Legacy cleanup for .kilocode/workflows and .kilocodemodes
  • Automated tests — suite 22 (config, IDE picker, install, skill output, legacy cleanup, reinstall)
  • Commit

Gemini CLI

Support assumption: full Agent Skills support. Gemini CLI docs confirm workspace skills at .gemini/skills/ and user skills at ~/.gemini/skills/. Also discovers .agents/skills/ as an alias. BMAD previously installed TOML files to .gemini/commands.

Install: npm install -g @google/gemini-cli or see geminicli.com

  • Confirm Gemini CLI native skills path is .gemini/skills/{skill-name}/SKILL.md (per geminicli.com/docs/cli/skills)
  • Implement native skills output — target_dir .gemini/skills, skill_format true, template_type default (replaces TOML templates)
  • Test fresh install — skills written to .gemini/skills/bmad-master/SKILL.md with correct frontmatter
  • Test reinstall/upgrade from legacy TOML command output — legacy dir removed, skills installed
  • Confirm no ancestor conflict protection is needed — Gemini CLI uses workspace > user > extension precedence, no ancestor directory inheritance
  • Implement/extend automated tests — 9 assertions in test suite 23 (config, fresh install, legacy cleanup, reinstall)
  • Manual CLI verification — gemini lists all 10 skills and successfully triggers bmad-help
  • Commit

iFlow

Support assumption: full Agent Skills support. iFlow docs confirm workspace skills at .iflow/skills/ and global skills at ~/.iflow/skills/. BMAD previously installed flat files to .iflow/commands.

  • Confirm iFlow native skills path is .iflow/skills/{skill-name}/SKILL.md
  • Implement native skills output — target_dir .iflow/skills, skill_format true, template_type default
  • Test fresh install — skills written to .iflow/skills/bmad-master/SKILL.md
  • Test legacy cleanup — legacy commands dir removed
  • Implement/extend automated tests — 6 assertions in test suite 24
  • NEEDS MANUAL IDE VERIFICATION — install iFlow and confirm skills appear in UI and can be triggered
  • Commit

QwenCoder

Support assumption: full Agent Skills support. Qwen Code supports workspace skills at .qwen/skills/ and global skills at ~/.qwen/skills/. BMAD previously installed flat files to .qwen/commands.

  • Confirm QwenCoder native skills path is .qwen/skills/{skill-name}/SKILL.md
  • Implement native skills output — target_dir .qwen/skills, skill_format true, template_type default
  • Test fresh install — skills written to .qwen/skills/bmad-master/SKILL.md
  • Test legacy cleanup — legacy commands dir removed
  • Implement/extend automated tests — 6 assertions in test suite 25
  • NEEDS MANUAL IDE VERIFICATION — install QwenCoder and confirm skills appear in UI and can be triggered
  • Commit

Rovo Dev

Support assumption: full Agent Skills support. Rovo Dev now supports workspace skills at .rovodev/skills/ and user skills at ~/.rovodev/skills/. BMAD previously used a custom 257-line installer that wrote .rovodev/workflows/ and prompts.yml.

  • Confirm Rovo Dev native skills path is .rovodev/skills/{skill-name}/SKILL.md (per Atlassian blog)
  • Replace 257-line custom rovodev.js with config-driven entry in platform-codes.yaml
  • Test fresh install — skills written to .rovodev/skills/bmad-master/SKILL.md
  • Test legacy cleanup — legacy workflows dir removed, prompts.yml BMAD entries stripped while preserving user entries
  • Implement/extend automated tests — 8 assertions in test suite 26
  • NEEDS MANUAL IDE VERIFICATION — install Rovo Dev and confirm skills appear in UI and can be triggered
  • Commit

Summary Gates

  • All full-support BMAD platforms install SKILL.md directory-based output
  • No full-support platform still emits BMAD command/workflow/rule files as its primary install format
  • Legacy cleanup paths are defined for every migrated platform
  • Automated coverage exists for config-driven and custom-installer migrations
  • Installer docs and migration notes updated after code changes land