Why this exists
I run Claude Code and Codex on the same workspaces. Claude auto-discovers the skills folder and quietly loads whatever applies. Codex ignored that folder completely: same workspace, same skills sitting right there, zero effect. Half my tooling was invisible to half my agents, and nothing errored, which is the worst kind of broken. The fix turned out to be a contract file: an AGENTS.md that lists each skill as required reading, with the path and one line saying when reading it is mandatory.
Once that file existed, Codex started behaving like it had the skills installed, because functionally it did. One contract file, two agents, one skill library. This skill writes that contract: it inventories the skills actually on disk, groups them by task domain so an agent can find the right one from the task in front of it, and keeps CLAUDE.md as a short pointer so there is never a second source of truth drifting out of date.
How it works
- It inventories what is actually installed Every skill folder at the workspace root, with its name and description read from the frontmatter. Linked skills from a shared library count the same as real folders. It also reads any existing AGENTS.md or CLAUDE.md so it extends rather than clobbers.
- It groups skills by task domain Design, Writing, Business, Development, Workflow: whatever fits the library, but two or three groups beat seven. An agent should find the right skill from the task in front of it, not from alphabetical order.
- It writes AGENTS.md as required reading Each skill gets a bold name, its workspace-relative path, and one line answering "when is reading this mandatory", not just "what is this". Hard workspace rules go at the bottom, applying to every output.
- It writes the CLAUDE.md pointer and verifies CLAUDE.md stays short and defers to AGENTS.md, one source of truth. Then the real test: ask the target agent in a fresh session to describe the workspace rules. If it cannot name the skills, the wording gets tightened.
Step by step (for first-time users)
-
Open the workspace root and type
/agents-md-writerRun it at the root where your skills folder lives, not inside an individual project. - Review the inventory It lists every skill it found on disk. Anything missing from the list will not make it into the contract; a contract pointing at missing files is worse than none.
- Approve the diff If an AGENTS.md or CLAUDE.md already exists, it shows exactly what changes before writing anything. Existing content is extended, never silently replaced.
- Test with the agent that was ignoring your skills Fresh session, ask it to describe the workspace rules. It should name the skills and when to read them. If not, rerun and tighten.
- Rerun after adding skills The contract only knows what was on disk when it was written. New skill, new run: it updates the registry in place.
The contract at a glance
| Agent | How it finds skills | What the contract adds |
|---|---|---|
| Claude Code | Auto-discovers the skills folder | A short CLAUDE.md pointer with load order for common task shapes |
| Codex and similar | Does not auto-load skills at all | AGENTS.md makes each SKILL.md required reading, with path and trigger |
| Any future agent that reads AGENTS.md | Varies | Inherits the same registry for free, no per-agent setup |
Honest take
What it does well: The per-skill line format is the load-bearing part. "When is reading this mandatory" is a completely different sentence from "what is this", and it is the difference between an agent that consults the skill library and one that acknowledges its existence. The verify step is the other honest touch: the contract is only done when a fresh session of the target agent can recite it back, and this skill treats a failed recital as its own bug to fix.
What it does not do: It does not make Codex execute skills the way Claude Code does; the skills are read as reference guidance and applied, not run as code. It only registers skills that exist on disk, so it will not scaffold placeholders for skills you are planning to write. And it enforces its own size limit: AGENTS.md stays under two screens, because it is a map, not documentation, and a bloated map stops being read.
When to use it: The day you add a second agent to a workspace that already has skills. After any batch of new skills, to refresh the registry. And once even in single-agent workspaces, honestly: writing down when each skill is mandatory turns out to sharpen how you use them with Claude Code too.