Creates and maintains system documentation entries in .codex/system_docs/ for agents and skills. Automatically invoked after new agents or skills are created to document their purpose, architecture, component locations, and integration points. Use when adding new agents, skills, or systems that need system_docs entries.
Manages the .codex/system_docs/ directory — the central reference mapping every agent, skill, config, and output path in the project. Automatically invoked after agent/skill creation to keep documentation in sync.
This skill should be invoked whenever:
.claude/agents/ or .codex/agents/.claude/skills/ or .codex/skills//system-docs-audit or /system-docs-audit --fix.codex/system_docs/
├── README.md ← Master index (MUST be updated for every change)
├── <system_name>/ ← One folder per "system"
│ ├── README.md ← REQUIRED: purpose, component map, integration points
│ ├── USAGE_GUIDE.md ← REQUIRED: how to use, quick start, examples, troubleshooting
│ ├── ARCHITECTURE.md ← STANDARD: technical diagrams, flows, state machines (2+ components)
│ ├── SYSTEM_OVERVIEW.md ← STANDARD: complete reference for back-referencing design decisions
│ ├── <subsystem>/ ← OPTIONAL: subfolder for coalescing sub-systems
│ │ └── README.md
│ └── <topic>.md ← OPTIONAL: domain-specific deep dives
└── deprecated/ ← Superseded systems
├── DEPRECATED.md
└── <old_system>/
| Level | Files Required | When |
|---|---|---|
| Minimum | README.md + USAGE_GUIDE.md | Every system |
| Standard | + ARCHITECTURE.md + SYSTEM_OVERVIEW.md | Systems with 2+ components |
| Extended | + subfolders + additional .md files | Complex multi-component systems |
Use a combination of ASCII art and Mermaid diagrams where appropriate:
Use Mermaid (```mermaid) for:
Use ASCII art for:
→ Folder / → Table entry)Rules:
See .claude/skills/system-docs-agent/references/ for templates:
example-readme.md — README structure with component mapexample-usage-guide.md — usage guide with quick start and troubleshootingexample-architecture.md — architecture doc with Mermaid diagramsA system is a group of related agents and/or skills that work together. Examples:
Standalone skills that don't have a dedicated agent or don't form a system go in the "Skills Not Mapped to System Docs" table in the master index instead of getting their own folder.
Does the agent/skill have:
- Multiple components (agent + skill + config)? → Folder
- An orchestrator/subagent pattern? → Folder
- Complex architecture worth documenting? → Folder
- Resource files or scripts? → Folder
- Just a single standalone skill? → Table entry
- A utility with no dedicated agent? → Table entry
Every system folder's README.md MUST follow this structure:
# <System Display Name>
System documentation for the <description> agents and skills.
## Purpose
<2-3 sentences explaining what this system does and why it exists.>
## When to Use
- <Bullet list of trigger conditions>
- <When should a user/agent invoke this system?>
## Architecture
<Diagram showing component relationships.
Use Mermaid for complex flows (```mermaid flowchart/sequence/state).
Use ASCII box-drawing (┌ ─ ┐ │ ├ ┤ └ ┘ ▼ ▲) for simple trees.>
## Key Concepts
<Brief explanations of important patterns or conventions specific to this system.>
## Workflow
<Numbered steps describing how the system operates end-to-end.>
## Agent & Skill Locations
| Component | Claude Path | Codex Path |
|-----------|-------------|------------|
| <Agent/Skill Name> | `.claude/<path>` | `.codex/<path>` |
## Integration with Other Systems
- **<system-name>**: <How this system relates to or depends on another system.>
The master index has three sections that MUST all be updated:
system_docs/
├── <system_name>/ ← <Display Name>
│ └── README.md
│ Agents:
│ .codex/agents/<agent-name>/
│ Skills:
│ .codex/skills/<skill-name>/
│ Config:
│ <config paths if any>
│ Output:
│ <output paths if any>
Table for standalone skills that don't warrant their own folder:
| Skill | Purpose | Related System |
|-------|---------|---------------|
| `skill-name` | Brief purpose | parent_system or — |
Summary table with counts:
| System | Purpose | Agent Count | Skill Count |
|--------|---------|-------------|-------------|
| <Name> | <Brief> | N | N |
Update the Total row at the bottom.
Read the YAML frontmatter and body of the new agent/skill to extract:
Apply the folder-vs-table decision tree above.
If folder:
.codex/system_docs/<system_name>/README.mdIf table entry:
Ensure .codex/system_docs/ changes exist in both:
| Element | Convention | Example |
|---|---|---|
| System folder | snake_case | game_development |
| README | Always README.md | README.md |
| Detail docs | kebab-case .md | architecture.md |
| Display names | Title Case | Game Development System |