From Docs to Skills, Plugins, and MCP
Split rules, workflows, distribution units, and external context into the right agent surface.
Key takeaways
- The goal is choosing the right surface for each kind of knowledge, not piling more text into one file.
- Rules files (
AGENTS.md,CLAUDE.md) are startup instructions; Skills are reusable procedures loaded on trigger; Plugins are versioned distribution units; MCP exposes Tools, Resources, and Prompts. - Promote a Skill to a Plugin only when it needs team distribution, packaged MCP config, hooks, and versioning, since a bad Plugin spreads faster than a bad local Skill.
- A common pattern is a thin rule file that names which Skill to use, with the detailed procedure inside the Skill and current facts supplied by an MCP Resource.
- Each surface carries security risks (prompt injection, Tool overreach, Skill drift, supply chain, Resource poisoning) with surface-specific mitigations.
Agentic documentation is not about putting more text into one file. It is about choosing the right surface for the right kind of knowledge.
Rules files are startup instructions. Skills are reusable procedures. Plugins are distribution units. MCP exposes tools, resources, and prompts from external systems.
Surface Selection
| Content | Recommended surface | Reason |
|---|---|---|
| Always-needed project rules | AGENTS.md, CLAUDE.md | loaded at task start |
| Path-specific rules | nested AGENTS.md, .claude/rules/ | avoids global bloat |
| Repeatable procedure | Skill | loaded only when triggered |
| Team-distributed workflows | Plugin | installable and versioned |
| API docs, DB schemas, policy docs | MCP Resource | external context |
| User-invoked workflow | MCP Prompt | structured task entry |
| External action | MCP Tool | explicit callable behavior |
Skills
A Skill is usually a SKILL.md plus optional scripts, references, and assets.
.agents/skills/release-check/
├── SKILL.md
├── scripts/
└── references/Use a Skill when:
- the same prompt is repeated often
- a checklist is too long for
AGENTS.md - scripts or reference files are needed
- the workflow is reusable across tasks
---
name: release-check
description: Use before release to summarize changes, detect risk, and list validation evidence.
---
1. Inspect the current diff and recent commits.
2. Classify user, operational, and migration impact.
3. Read `references/release-policy.md` only when needed.
4. Report validation commands and residual risk.Plugins
Promote a Skill to a Plugin when the workflow needs team distribution, packaged MCP config, app integrations, hooks, versioning, and install policy.
docs-quality-plugin/
├── .codex-plugin/
│ └── plugin.json
├── skills/
├── .mcp.json
└── assets/Do not package experimental workflows too early. A bad Plugin spreads faster than a bad local Skill.
MCP
MCP servers expose three major building blocks.
| MCP feature | Meaning | Documentation concern |
|---|---|---|
| Tools | callable actions | input/output schema, auth, side effects |
| Resources | read-only context | freshness, owner, source URL |
| Prompts | user-invoked templates | arguments, workflow boundaries |
docs://api/openapi.yaml
docs://adr/2026-05-billing.md
kb://support/refund-policy
schema://warehouse/ordersCommon Patterns
Thin rule file, thick Skill
AGENTS.md says which Skill to use. The Skill contains the detailed procedure.
Skill plus MCP Resource
The Skill contains the workflow. The MCP Resource supplies current facts.
Plugin for distribution
Once a Skill and MCP setup are stable, bundle them as a Plugin with ownership, versioning, and review.
Security Boundaries
| Risk | Example | Mitigation |
|---|---|---|
| Prompt injection | Resource text says "ignore rules" | treat Resource text as data |
| Tool overreach | review Skill calls deploy Tool | approval and per-tool policy |
| Skill drift | old CI command | smoke tests and freshness |
| Plugin supply chain | unknown plugin source | manifest and owner review |
| Resource poisoning | stale schema | generated_at, source URL, checksum |