0005 — Docs are canonical knowledge and skills are the agent execution layer

Status: Accepted Date: 2026-05-01 Deciders: docs platform, agent tooling Supersedes: — Superseded by: —

Context

Wordloop maintains both a documentation site and a set of agent skills. The docs site is built for humans and agents: it publishes navigable pages, llms.txt, llms-full.txt, per-page Markdown exports, and MCP resources. The skills are loaded by AI agents to guide task execution.

The previous stance kept docs and skills as fully separate surfaces. That avoided prompt-like content leaking into the docs site, but it also created a drift risk: durable engineering policy could be duplicated in both docs and skill files. We have already seen signs of this class of drift, such as stack-version claims differing between service docs and package metadata.

Modern skill design favours progressive disclosure: concise trigger metadata, a short operating contract, and selective loading of deeper references. This means skill files should not become large documentation mirrors. They should tell the agent what to read, how to act, and how to verify.

Decision

The documentation site is the canonical source for durable engineering knowledge. Agent skills are the execution layer that selects, loads, and applies that knowledge safely.

A docs page owns:

• Principles and architecture guidance.
• Service handbooks and implementation conventions.
• Workflow guides and runbooks.
• ADRs and decision history.
• Generated reference material from specs, schemas, and code.
• Glossary and domain vocabulary.

A skill owns:

• Triggering and task routing.
• Which docs pages to read for each task shape.
• Tool usage, command sequencing, and safety gates.
• Verification steps and eval discipline.
• Agent-specific constraints that do not belong in human-facing docs.

Skills may reference docs pages by slug or MCP resource. Docs pages must not depend on skill internals for their meaning.

Consequences

• Durable guidance has one canonical maintenance path.
• Human and agent readers consume the same engineering knowledge.
• Skills remain smaller, more triggerable, and easier to evaluate.
• Documentation changes can identify affected skills through a skill-to-doc map.
• Skill changes can identify which canonical docs pages need review.
• The docs site needs stronger freshness, metadata, and health checks because more agent behaviour depends on it.

Alternatives considered

• Keep docs and skills completely separate. Rejected because it preserves duplicated policy and makes drift a review-discipline problem only.
• Move most docs into skills. Rejected because skills are not a good human-reading surface and large skill files weaken progressive disclosure.
• Have skills fetch arbitrary public documentation at runtime. Rejected as the default because public retrieval introduces prompt-injection and freshness risks. Trusted local docs, generated Markdown exports, and the Wordloop MCP server are the default context path.
• Generate skills entirely from docs. Deferred. It may become useful for simple doc-reference sections, but skill trigger wording and safety gates still need deliberate evaluation.

Debt annotation

Principal: Medium. We need a skill-to-doc map, workflow docs, freshness metadata, and documentation health checks.

Interest: Low if automated checks run in CI; high if this remains a manual checklist.

Multiplier: Agent autonomy. The more agents rely on docs for task execution, the more expensive stale docs become.

Verification

• Each maintained skill declares its canonical docs dependencies in the skill-to-doc map.
• Documentation health checks validate mapped docs pages exist.
• Stale active docs are flagged by review cadence.
• Skill updates include a docs review step.
• Docs updates include an affected-skills review step.

Related

• Documentation
• Agent-Native Systems
• Keep Docs and Skills in Sync
• Correct Documentation Drift