Why
Currently if there are skills in repos referenced by the workspace folder, the skills frontmatter for those repos are not added to the AI context.
We should discover skills from workspace repositories during sync and embed them in the WORKSPACE-RULES section of AGENTS.md so AI agents can find and load repo-local skills.
Agreed Design
Behavior
- During
sync, scan each workspace repo for skills in client-specific directories (.claude/skills/, .agents/skills/, .codex/skills/, etc.)
- Parse
name and description from each SKILL.md frontmatter
- Embed an
<available_skills> XML block directly in the <!-- WORKSPACE-RULES --> section of AGENTS.md (no separate file)
- Paths are relative from AGENTS.md (workspace root)
- Skip symlinks/junctions when scanning
workspace.yaml Schema
The skills field on repositories controls discovery:
repositories:
- path: ../repo-a # omitted: auto-discover from client skill paths
- path: ../repo-b
skills: # array: scan only these custom paths (relative to repo root)
- plugins/foo/skills
- plugins/bar/skills
- path: ../repo-c
skills: false # disabled: skip entirely
- omitted /
true → auto-discover from default client paths (derived from clients in workspace.yaml)
string[] → scan only these custom paths (overrides defaults)
false → skip skill discovery for this repo
Output Format
## Workspace Skills
When a task matches a skill description, fetch the full instructions from its location.
<available_skills>
<skill>
<name>my-skill</name>
<description>Does something useful</description>
<location>../my-repo/.claude/skills/my-skill/SKILL.md</location>
</skill>
</available_skills>
Implementation Plan
See .claude/plans/2026-03-26-workspace-skills-index.md on branch feat/310-workspace-skills-index.
6 tasks (TDD):
- Add
skills field to RepositorySchema (boolean | string[], optional)
- New
src/core/repo-skills.ts — discoverRepoSkills() scans dirs, parses frontmatter, skips symlinks
- Update
generateWorkspaceRules() to render <available_skills> XML
- Wire discovery into
updateAgentFiles() → ensureWorkspaceRules() pipeline + copyWorkspaceFiles() path
- Integration tests
- Manual E2E validation
Why
Currently if there are skills in repos referenced by the workspace folder, the skills frontmatter for those repos are not added to the AI context.
We should discover skills from workspace repositories during sync and embed them in the WORKSPACE-RULES section of AGENTS.md so AI agents can find and load repo-local skills.
Agreed Design
Behavior
sync, scan each workspace repo for skills in client-specific directories (.claude/skills/,.agents/skills/,.codex/skills/, etc.)nameanddescriptionfrom each SKILL.md frontmatter<available_skills>XML block directly in the<!-- WORKSPACE-RULES -->section of AGENTS.md (no separate file)workspace.yamlSchemaThe
skillsfield on repositories controls discovery:true→ auto-discover from default client paths (derived fromclientsin workspace.yaml)string[]→ scan only these custom paths (overrides defaults)false→ skip skill discovery for this repoOutput Format
Implementation Plan
See
.claude/plans/2026-03-26-workspace-skills-index.mdon branchfeat/310-workspace-skills-index.6 tasks (TDD):
skillsfield toRepositorySchema(boolean | string[], optional)src/core/repo-skills.ts—discoverRepoSkills()scans dirs, parses frontmatter, skips symlinksgenerateWorkspaceRules()to render<available_skills>XMLupdateAgentFiles()→ensureWorkspaceRules()pipeline +copyWorkspaceFiles()path