feat: support portable producer skill roots

[osolmaz]

Opened on behalf of Onur Solmaz (osolmaz).

Summary

Producer CLIs could only use findSkillsRoot() when their bundled skills lived under skills/.
This change makes .agents/skills/ a first-class producer layout too.
It keeps the old skills/ behavior, adds multi-root support, and documents the portable layout.

What Changed

Skill discovery now understands both conventional package skills and portable repo-local agent skills.
Existing callers that use skills/ keep working unchanged.

• Added findSkillsRoots() for CLIs that intentionally ship more than one root.
• Made findSkillsRoot() prefer skills/ and fall back to .agents/skills/.
• Allowed handleSkillflag() and maybeHandleSkillflag() to receive one root or an array of roots.
• Deduplicated resolved roots before listing, showing, exporting, or installing.
• Updated README, integration docs, and the bundled skillflag skill.
• Added regression tests for .agents/skills discovery and multi-root listing.

Testing

I ran the package gates and the new tests pass.

• npm run format
• npm run build
• npm run lint
• npm run format:check
• npm test

Risks

The compatibility risk is low because skills/ remains the preferred root and the public skillsRoot option still accepts the original URL/string inputs.
The only behavior change is that a missing skills/ directory can now resolve to .agents/skills/ instead of throwing.

[osolmaz]

Final validation report:

• Implemented .agents/skills producer-root discovery while preserving skills/ as the preferred root.
• Added findSkillsRoots() and multi-root skillsRoot support.
• Updated README, integration docs, bundled skill docs, and regression tests.
• Local validation passed:
  • npm run format
  • npm run build
  • npm run lint
  • npm run format:check
  • npm test
• Codex review found no actionable correctness issues. The review sandbox could not run temp-dir tests because it was read-only, but local full tests passed.
• GitHub CI check lint-and-test is green.