Discover standard agent skill paths

[Waishnav]

Summary

• discover ~/.agents/skills and workspace .agents/skills by default
• keep DEVSPACE_AGENT_DIR/skills and DEVSPACE_SKILL_PATHS support while making project .pi/skills opt-in through DEVSPACE_SKILL_PATHS
• document .agents/skills as the standard Agent Skills convention

Verification

• npx tsx src/skills.test.ts && npx tsx src/config.test.ts
• npm run typecheck

Closes #28

Summary by CodeRabbit

• New Features
  • Expanded Agent Skill discovery to include standard user (~/.agents/skills) and project (./.agents/skills) locations, plus compatibility with prior skill directory conventions.
  • Enhanced discovery by adding an ordered, environment-configurable set of extra skill directories.
• Bug Fixes
  • Improved skill discovery to only use directories that actually exist, resulting in more reliable “skills do not appear” outcomes.
  • DEVSPACE_SKILL_PATHS entries are now taken as provided (no automatic home-path expansion).
• Documentation
  • Refreshed Skills configuration and troubleshooting guidance with the full discovery location breakdown.
• Tests
  • Broadened coverage for user/project-scoped skills and legacy discovery scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3089f0fe-d209-4286-ad57-1c71aad4b168

📥 Commits

Reviewing files that changed from the base of the PR and between 3ea42e1 and 4ab5e85.

📒 Files selected for processing (3)

• src/config.ts
• src/skills.test.ts
• src/skills.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/skills.ts
• src/skills.test.ts

---

📝 Walkthrough

Walkthrough

Adds effectiveSkillPaths to compute workspace skill directories from ~/.agents/skills, <cwd>/.agents/skills, and DEVSPACE_AGENT_DIR/skills, then uses it in loadWorkspaceSkills with includeDefaults disabled. Tests and documentation are updated to reflect the revised discovery paths.

Changes

Skill discovery path expansion

Layer / File(s)	Summary
effectiveSkillPaths helper and loadWorkspaceSkills update src/skills.ts, src/config.ts	Stops parsing skill paths into resolved absolute paths in config, then implements effectiveSkillPaths to filter existing candidate directories, expand ~, resolve absolute paths, and deduplicate; updates loadWorkspaceSkills to call effectiveSkillPaths and set includeDefaults: false.
Test fixtures and assertions for new discovery paths src/skills.test.ts	Extends setup with agent-global and agent-project skill fixtures plus HOME/USERPROFILE overrides and restore logic; adds assertions for the new discovery set, effectiveSkillPaths, and a legacy .pi/skills scenario.
Documentation updates for skill discovery docs/configuration.md, docs/gotchas.md, docs/chatgpt-coding-workflow.md	Expands Skills sections to document standard (~/.agents/skills, project .agents/skills), compatibility (DEVSPACE_AGENT_DIR/skills defaulting to ~/.codex/skills), and legacy (.pi/skills via DEVSPACE_SKILL_PATHS) discovery locations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hop through paths both old and new,
~/.agents/skills now shines through.
With defaults trimmed and routes aligned,
The rabbit finds each skill in time.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and matches the main change: adding standard agent skill path discovery.
Linked Issues check	✅ Passed	The PR satisfies #28 by adding ~/.agents/skills to default discovery and keeping the documented compatibility paths.
Out of Scope Changes check	✅ Passed	The changes stay focused on skill discovery, documentation, and tests, with no clearly unrelated code paths introduced.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/issue-28-agent-skill-paths

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/skills.ts`:
- Around line 31-35: The skill path deduplication in `src/skills.ts` is
resolving configured entries against the current process directory instead of
the workspace cwd, so relative `config.skillPaths` can miss collisions with the
default workspace path and get scanned twice. Update the path normalization in
this filter to resolve configured skill paths relative to the workspace cwd used
when loading `DEVSPACE_SKILL_PATHS`, and keep the duplicate check in the `seen`
set based on that workspace-resolved path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d8e69fd6-3c92-4cda-9a0f-f924eb2046ba

📥 Commits

Reviewing files that changed from the base of the PR and between 89d99c9 and 7d360cc.

📒 Files selected for processing (5)

• docs/chatgpt-coding-workflow.md
• docs/configuration.md
• docs/gotchas.md
• src/skills.test.ts
• src/skills.ts