Team Documentation Culture
Govern agent instructions, Skills, Plugins, MCP servers, ownership, and rollout.
Written and reviewed by Eric Han · Co-founder & CTO, reopt
Key takeaways
- When
AGENTS.md, Skills, Plugins, and MCP servers shape agent behavior, documentation culture becomes governance. - Assign an owner and reviewer to every surface and set risk levels, with high-risk surfaces like Plugins and MCP servers requiring security review.
- Encode a change policy where each surface has a required reviewer and destructive Tools or OpenAPI breaking changes get separate approval or migration notes.
- Roll out in phases (baseline rules, then API/runbook/KB contracts, then Skills/MCP checks, then Plugins/governance) instead of a big-bang migration.
- Measure ROI against a local baseline (agent rework, onboarding time, MTTR, breaking changes caught, freshness, blocked destructive actions) and avoid inflated claims.
In agentic documentation, culture becomes governance. If AGENTS.md, Skills, Plugins, and MCP
servers influence agent behavior, teams need ownership, review rules, and retirement policies.
Ownership by Surface
| Surface | Owner | Reviewer | Risk |
|---|---|---|---|
AGENTS.md | repo owner | tech lead | high |
CLAUDE.md | repo owner | tech lead | medium |
.claude/rules/ | area owner | area reviewer | medium |
| Skills | workflow owner | domain owner | medium to high |
| Plugin | platform team | security + platform | high |
| MCP server | platform/security | security + data owner | high |
| OpenAPI | API owner | consumer representative | high |
| KB/RAG index | docs/platform | domain owner | medium |
Change Policy
## Agent Documentation Change Policy
- `AGENTS.md`: tech lead review required
- `CLAUDE.md`: repo owner review required
- path rules: owning area review required
- Skill change: workflow owner review
- Plugin change: platform + security review
- MCP Tool addition: data owner + security review
- destructive Tool: separate approval required
- OpenAPI breaking change: migration note requiredRollout Phases
ROI Metrics
| Metric | Measure |
|---|---|
| agent rework | PR correction comments, retry count |
| onboarding | time to first merged PR |
| operations | MTTR for runbook-backed incidents |
| API quality | breaking changes caught by diff |
| freshness | docs past review_after |
| security | blocked unapproved destructive actions |
Anti-patterns
| Anti-pattern | Problem | Better |
|---|---|---|
| Big-bang migration | burnout | start with shared rules |
| Tool-first rollout | no owner | assign owners first |
| Rule accumulation | huge AGENTS.md | move procedures to Skills |
| Plugin sprawl | unreviewed workflows spread | promote only stable Skills |
| vague authority | unsafe Tool execution | least privilege and approval |
| inflated ROI claims | trust loss | measure local baseline |
Checklist
| Item | Check |
|---|---|
| every agent surface has an owner | [ ] |
AGENTS.md and CLAUDE.md conflicts are reviewed | [ ] |
| Skill-to-Plugin promotion criteria exist | [ ] |
| MCP Tool additions require data/security review | [ ] |
| destructive actions have approval policy | [ ] |
| stale rules and unused Skills are cleaned monthly | [ ] |