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

16 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
  • NEEDS MANUAL IDE VERIFICATION — install Crush via brew and confirm skills appear in UI
  • 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

Support assumption: full Agent Skills support. BMAD currently uses a custom installer that writes .kilocodemodes and .kilocode/workflows; target should move to native skills output.

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

  • Confirm KiloCoder native skills path is .kilocode/skills/{skill-name}/SKILL.md (Kilo forked from Roo Code which uses .roo/skills/)
  • Design the migration away from modes plus workflow markdown — replaced 269-line custom kilo.js with config-driven installer entry in platform-codes.yaml
  • Implement native skills output — target_dir .kilocode/skills, skill_format true, template_type default
  • Add legacy cleanup for .kilocode/workflows (via legacy_targets) and BMAD-owned entries in .kilocodemodes (via cleanupKiloModes() in _config-driven.js, same pattern as copilot-instructions.md cleanup)
  • Test fresh install — skills written to .kilocode/skills/bmad-master/SKILL.md with correct frontmatter
  • Test reinstall/upgrade from legacy custom installer output — legacy workflows removed, skills installed
  • Confirm no ancestor conflict protection is needed — Kilo Code (like Cline) only scans workspace-local .kilocode/skills/, no ancestor directory inheritance
  • Implement/extend automated tests — 11 assertions in test suite 22 (config, fresh install, legacy cleanup, .kilocodemodes 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 @anthropic-ai/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)
  • 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