Summary
bmad-loop's skill lookup treats every skill_tree as a project-relative path and resolves
it strictly as {project_root}/{skill_tree}. It never expands ~ or consults a user-level
skills directory, and the CLI-profile validator additionally rejects absolute/sibling
(..) spellings of skill_tree. So skills that live in the user's global
~/.agents/skills (the tree DSH, Codex, Gemini, Copilot, etc. load) are invisible to
bmad-loop validate unless the project happens to carry its own copy or a junction back to
the user directory.
Environment
- bmad-loop 0.11.1 (Windows 11,
win32)
- Policy adapter:
opencode-http (but the same applies to codex/gemini/etc. profiles,
whose shipped skill_tree is .agents/skills)
- The host keeps the BMAD/DSH dev+review skills in the global
C:\Users\<user>\.agents\skills
(bmad-build-auto, bmad-review, …) — the same tree the local agents already use.
Expected behavior
A user whose skills live in ~/.agents/skills should be able to point bmad-loop at that
tree and have validate (and dev/review dispatch) find them — ideally by letting
skill_tree accept a ~-expanded / absolute path, or by falling back to a user-level
candidate directory when the project-relative path is absent.
Actual behavior / repro (as-is)
- In a project set
.bmad-loop/policy.toml [adapter] name = "opencode-http" (shipped
skill_tree = ".agents/skills").
- Have
C:\Users\<user>\.agents\skills\bmad-build-auto\SKILL.md and
bmad-review\SKILL.md present (global).
bmad-loop validate --project <proj> reports:
FAIL: .agents/skills/bmad-build-auto not found — …
FAIL: .agents/skills/bmad-review-adversarial-general not found — …
FAIL: .agents/skills/bmad-review-edge-case-hunter not found — …
even though the skills exist globally. The only way to make it green without installing a
project-local copy is a directory junction {project}/.agents/skills -> ~/.agents/skills
(gitignored), which is a per-machine hack that does not survive clone/CI.
Root-cause pointers
- Skill trees are collected per profile at
cli.py _skill_trees: trees.append(get_profile(name, project).skill_tree)
— a bare relative string.
- Every lookup then joins it onto the project root, e.g. in
install.py:
resolve_dev_primitive: _is_file(project / tree / <dev_primitive> / "SKILL.md")
missing_base_skills: project / tree / <skill> / "SKILL.md" and the review-layers/
consolidated checks project / tree / MERGED_REVIEW_SKILL / "SKILL.md"
- all of which are
project / tree, never Path.home() / tree.
- The validator refuses non-project-relative skill trees in
adapters/profile.py _validate_profile:
skill_tree must satisfy
not names_tree_root(...) and not is_absolute_path(...) and not has_parent_ref(...)
(project-relative path) — so a user cannot simply set skill_tree = "~/…" or an
absolute path today.
Requested change
- Let
skill_tree accept a ~-prefix (expanded via Path.expanduser()) and/or an absolute
path, and honor it when resolving skill locations (validate + dispatch + worktree
provisioning).
- Alternatively/additionally: when the project-relative tree is absent, fall back to a
user-level candidate (~/.agents/skills, per the same .agents/skills convention) so a
global install is honored without any project scaffolding.
- Consistency: apply the same resolution wherever skills are probed/loaded
(_skill_trees, resolve_dev_primitive, missing_base_skills, the review/renderer
checks, and install's bmad-loop init skill layout).
Notes
- This is a companion to the bmad-loop ↔ BMAD-METHOD config-layout version mismatch; on a
fresh project with current tooling, validate can only be brought to green by
non-portable project scaffolding (junction/copy). Supporting a user-level skill tree
removes that need.
- Happy to run probe commands or provide full
validate output / a minimal project layout
if useful.
Summary
bmad-loop's skill lookup treats every
skill_treeas a project-relative path and resolvesit strictly as
{project_root}/{skill_tree}. It never expands~or consults a user-levelskills directory, and the CLI-profile validator additionally rejects absolute/sibling
(
..) spellings ofskill_tree. So skills that live in the user's global~/.agents/skills(the tree DSH, Codex, Gemini, Copilot, etc. load) are invisible tobmad-loop validateunless the project happens to carry its own copy or a junction back tothe user directory.
Environment
win32)opencode-http(but the same applies tocodex/gemini/etc. profiles,whose shipped
skill_treeis.agents/skills)C:\Users\<user>\.agents\skills(
bmad-build-auto,bmad-review, …) — the same tree the local agents already use.Expected behavior
A user whose skills live in
~/.agents/skillsshould be able to point bmad-loop at thattree and have
validate(and dev/review dispatch) find them — ideally by lettingskill_treeaccept a~-expanded / absolute path, or by falling back to a user-levelcandidate directory when the project-relative path is absent.
Actual behavior / repro (as-is)
.bmad-loop/policy.toml[adapter] name = "opencode-http"(shippedskill_tree = ".agents/skills").C:\Users\<user>\.agents\skills\bmad-build-auto\SKILL.mdandbmad-review\SKILL.mdpresent (global).bmad-loop validate --project <proj>reports:project-local copy is a directory junction
{project}/.agents/skills -> ~/.agents/skills(gitignored), which is a per-machine hack that does not survive clone/CI.
Root-cause pointers
cli.py_skill_trees:trees.append(get_profile(name, project).skill_tree)— a bare relative string.
install.py:resolve_dev_primitive:_is_file(project / tree / <dev_primitive> / "SKILL.md")missing_base_skills:project / tree / <skill> / "SKILL.md"and the review-layers/consolidated checks
project / tree / MERGED_REVIEW_SKILL / "SKILL.md"project / tree, neverPath.home() / tree.adapters/profile.py_validate_profile:skill_treemust satisfynot names_tree_root(...) and not is_absolute_path(...) and not has_parent_ref(...)(
project-relative path) — so a user cannot simply setskill_tree = "~/…"or anabsolute path today.
Requested change
skill_treeaccept a~-prefix (expanded viaPath.expanduser()) and/or an absolutepath, and honor it when resolving skill locations (validate + dispatch + worktree
provisioning).
user-level candidate (
~/.agents/skills, per the same.agents/skillsconvention) so aglobal install is honored without any project scaffolding.
(
_skill_trees,resolve_dev_primitive,missing_base_skills, the review/rendererchecks, and
install'sbmad-loop initskill layout).Notes
fresh project with current tooling,
validatecan only be brought to green bynon-portable project scaffolding (junction/copy). Supporting a user-level skill tree
removes that need.
validateoutput / a minimal project layoutif useful.