Skip to main content
reopt Handbook
reopt Handbook
Agentic Documentation

Paradigm Shift

Why Documentation Must ChangeAI-readable Design PrinciplesAI-assisted Writing Process

Practice by Document Type

Project Rule DocumentsFrom Docs to Skills, Plugins, and MCPAgent Documentation SecurityAPI Docs and SpecsREADME and OnboardingArchitecture Decision RecordsRunbooks and OperationsUser Guides and TutorialsKnowledge Bases and Internal Wikis

Operations

Maintenance StrategyTeam Documentation Culture

Appendix

TemplatesVerification ReportUpdates
Handbook›에이전틱 시대의 문서화 혁신›Team Documentation Culture
한국어English

Team Documentation Culture

Govern agent instructions, Skills, Plugins, MCP servers, ownership, and rollout.

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

SurfaceOwnerReviewerRisk
AGENTS.mdrepo ownertech leadhigh
CLAUDE.mdrepo ownertech leadmedium
.claude/rules/area ownerarea reviewermedium
Skillsworkflow ownerdomain ownermedium to high
Pluginplatform teamsecurity + platformhigh
MCP serverplatform/securitysecurity + data ownerhigh
OpenAPIAPI ownerconsumer representativehigh
KB/RAG indexdocs/platformdomain ownermedium

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 required

Rollout Phases

ROI Metrics

MetricMeasure
agent reworkPR correction comments, retry count
onboardingtime to first merged PR
operationsMTTR for runbook-backed incidents
API qualitybreaking changes caught by diff
freshnessdocs past review_after
securityblocked unapproved destructive actions

Anti-patterns

Anti-patternProblemBetter
Big-bang migrationburnoutstart with shared rules
Tool-first rolloutno ownerassign owners first
Rule accumulationhuge AGENTS.mdmove procedures to Skills
Plugin sprawlunreviewed workflows spreadpromote only stable Skills
vague authorityunsafe Tool executionleast privilege and approval
inflated ROI claimstrust lossmeasure local baseline

Checklist

ItemCheck
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[ ]

Related docs

CRM Strategy

CRM Standard · Align CRM purpose, ownership, and priorities from a leadership perspective.

Updates

Change log for the Agentic Documentation handbook.

Agent Documentation Security

Reduce prompt injection, MCP tool poisoning, Plugin supply chain risk, and excessive agency.

Operations: Entropy and Garbage Collection

Harness Engineering · Explain how harnesses decay and how teams keep docs, workflows, permissions, hooks, and runtime surfaces current.

Governance and Collaboration

Design Systems for the AI Era · Ownership, change management, and quality gates for AI-ready design systems.

Maintenance Strategy

Keep docs, instructions, Skills, Plugins, MCP Resources, and validation loops from drifting.

Templates

Templates for AGENTS.md, CLAUDE.md, Skills, Plugins, MCP, llms.txt, runbooks, and KB docs.

On this page

Ownership by SurfaceChange PolicyRollout PhasesROI MetricsAnti-patternsChecklist