Fix Docs
Documentsfix-docsFix Docs is an Agent Skill for documents published in the marin-community/marin repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
De-rot markdown docs in lib/iris, lib/zephyr, and lib/fray.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/marin-community/marin/blob/HEAD/.agents/skills/fix-docs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/fix-docs, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Fix the markdown docs within lib/iris, lib/zephyr and lib/fray so they
comply with the principles below. Do NOT touch docs outside those directories.
Output: dispatch sub-agents that (1) parse the code and docs and (2) make the documentation changes locally. Commit the changes into a single local commit, inform the user, and summarize what changed. Never push without explicit user approval.
Principles
- Agents are the primary consumers of documentation. Coding agents write
most Marin code; humans use agents as "documentation brokers". Segregate docs
by audience:
- Human docs live in
docs/— high-level, "getting started", concise. - Agent docs live in the directory tree next to the code they describe — token-efficient.
- Human docs live in
- Agentic docs follow standards so agents know where to look. Entry points:
**/AGENTS.md— targeted agent guidance for the subtree, plus a recursive ToC/index of subtree content.**/OPS.md— field guide for gathering telemetry, running commands, and debugging the systems in the subtree..agents/skills/*/SKILL.md— prompts for common agentic workflows.
- Avoid rot. Rot confuses agents and wastes context. When a doc is out of
date with the code: update it (if recent and the change is small) or archive
it to
.agents/projects/YYYYMMDD_filename.md(if historical-only; date from the first commit viagit). The code is the source of truth. - Context quality and quantity are paramount. Model performance degrades on
a full context window. Agent docs should focus on:
- "Negative guidance": assume agents are smart; document sharp edges based on observed suboptimal agent behavior.
- Using markdown as indexes/ToC for context efficiency ("for X, read file Y").
Common issues
- Stale design docs that guided initial system design — move to
.agents/projects/YYYYMMDD_filename.md, dated from the first commit (git).