ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/tools/docs/native-skills-migration-che...

18 KiB
Raw Blame History

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 — SUSPENDED

Status: Kilo Code does not support the Agent Skills standard. The original migration assumed skills support because Kilo forked from Roo Code, but manual IDE verification confirmed Kilo has not merged that feature. BMAD support is paused until Kilo implements skills.

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

  • Confirm KiloCoder native skills path — FALSE: assumed from Roo Code fork, not verified. Manual testing showed no skills support in the IDE
  • Config and installer code retained in platform-codes.yaml with suspended flag — hidden from IDE picker, setup blocked with explanation
  • Installer fails early (before writing _bmad/) if Kilo is the only selected IDE, protecting existing installations
  • Legacy cleanup still runs for .kilocode/workflows and .kilocodemodes when users switch to a different IDE
  • Automated tests — 7 assertions in suite 22 (suspended config, hidden from picker, setup blocked, no files written, legacy cleanup)

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)
  • Add legacy cleanup for .gemini/commands (via legacy_targets)
  • 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
  • Add legacy cleanup for .iflow/commands (via legacy_targets)
  • 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
  • Add legacy cleanup for .qwen/commands (via legacy_targets)
  • 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
  • Add legacy cleanup for .rovodev/workflows (via legacy_targets) and BMAD entries in prompts.yml (via cleanupRovoDevPrompts() in _config-driven.js)
  • 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