🤖 feat: add workspace universal skills path and concurrent loading

[ammar-agent]

Summary

Follow-up to #2419: add workspace universal skill loading from .agent/skills and parallelize skill root/descriptor loading to reduce latency (especially for remote runtimes).

Background

The initial universal-path support added ~/.agents/skills, but users also keep universal skills in workspace-level .agent/skills. Also, skill discovery/read paths were still mostly serialized, which can amplify SSH latency.

Implementation

• Added workspace universal default root:
  • <projectRoot>/.agent/skills
• Kept universal roots under global precedence semantics:
  • project .mux/skills
  • ~/.mux/skills
  • <projectRoot>/.agent/skills
  • ~/.agents/skills
  • built-ins fallback
• Refactored discovery internals to:
  • resolve/list all roots concurrently
  • group candidates by skill name
  • resolve descriptor candidates concurrently across skills (with ordered fallback per skill name)
• Refactored readAgentSkill to probe candidate roots concurrently while preserving precedence in selection.
• Added tests covering:
  • default roots include workspace/home universal paths
  • workspace/home universal discovery semantics
  • fallback when higher-precedence skill is invalid
• Updated docs/tool descriptions to include .agent/skills.

Validation

• bun test src/node/services/agentSkills/agentSkillsService.test.ts
• make typecheck
• make static-check

Risks

Low-to-moderate. This is a behavior-preserving refactor with more concurrency and one additional root, but it touches core discovery/read flow. Tests were expanded for precedence and fallback behavior.

---

Generated with mux • Model: openai:gpt-5.3-codex • Thinking: xhigh • Cost: $0.00