Add agent config files (opencode.json, .claude/, CLAUDE.md, .codex/) for skill discoverability

[lluisinthedesert]

Problem

The skill library in skills/ contains 7 capability playbooks (understudy, capture-evidence, optimize-workload, optimize-agentic-search, use-understudy-gateway, run-local-model-lab, prepare-verifier-handoff) but no agent-configuration files exist in the repo to surface these skills to coding agents. An agent has to manually explore the repo tree to discover them, which means the skills are effectively invisible to opencode, Claude Code, Codex, and similar tools unless the user already knows to look.

Proposal

Add agent-discovery files that point at the existing skill library:

1. opencode.json (opencode)

• Add skills.paths pointing to ./skills so opencode auto-discovers all **/SKILL.md files.
• Optionally set instructions to ["AGENTS.md", "skills/README.md"] so the skill index is loaded into context.
• Schema: https://opencode.ai/config.json

2. CLAUDE.md (Claude Code)

• Add a CLAUDE.md at the repo root that references the skill library and its entry point (skills/understudy/SKILL.md).
• Claude Code auto-reads CLAUDE.md from the repo root.

3. .claude/ directory (Claude Code skills)

• Symlink or copy skill references into .claude/skills/ so Claude Code can load them natively.
• Alternatively, .claude/commands/ for slash-command shortcuts.

4. .codex/ directory (OpenAI Codex)

• Add codex.md or instructions under .codex/ pointing at the skill library.

Benefits

• Agents using any of these tools will immediately see the full understudy skill library without manual exploration.
• The existing skill content does not need to change — only discovery/pointer files are added.
• Progressive disclosure is preserved: the orchestrator skill (understudy/SKILL.md) routes to workers, and workers route to deeper reference.md docs.

Considerations

• Keep pointer files minimal — they reference the skill library, they do not duplicate it.
• Ensure the opencode.json $schema field is set so editors validate it.
• Symlinks may not work across all platforms; consider whether to copy or reference.
• The skill description frontmatter already serves as the trigger text for skill matching, so the agent-config files mainly need to ensure the skill paths are scanned.

Related

• skills/README.md — existing skill index
• AGENTS.md — existing repo-level agent instructions
• Skill frontmatter description fields — already written for agent trigger matching

[Dipxssi]

Hey ! @lluisinthedesert
I'm working on this PR and will submit the implementation soon.

[Dipxssi]

Hey ! @lluisinthedesert
Before raising a PR ,I had one quick question. I was planning not to add .claude/skills/ copies/symlinks, since the repository already includes .claude-plugin/marketplace.json and AGENTS.md documents the plugin installation flow. My thinking was that mirroring the skills under .claude/skills/ would create duplicate skills and require keeping two copies in sync.

Does that sound right, or would you prefer .claude/skills/ to be included in this PR ?

[Dipxssi]

Following up on my earlier comment: I went ahead and included the .claude/skills/ symlinks to align with the expectations of Issue #35.