Skip to content

Support global / user-level skill trees (e.g. ~/.agents/skills), not just project-relative #770

Description

@pinghe

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)

  1. In a project set .bmad-loop/policy.toml [adapter] name = "opencode-http" (shipped
    skill_tree = ".agents/skills").
  2. Have C:\Users\<user>\.agents\skills\bmad-build-auto\SKILL.md and
    bmad-review\SKILL.md present (global).
  3. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions