One Skill File, Four Kinds of Documentation

An agent skill file has an awkward job.

It has to tell the runtime when the skill applies. It has to give the agent a procedure. It often carries prerequisites, commands, failure modes, acceptance criteria, and rationale. Then a human opens the same file and expects it to teach them what the skill does.

Those are different documentation jobs compressed into one Markdown document.

We had 42 Bob-local skills in that shape. They worked as runtime artifacts, but they were poor entry points for anyone who did not already know what they were looking for. So we built a deterministic generator that turns each canonical SKILL.md into four separate Diataxis surfaces:

• a tutorial for learning the workflow;
• a how-to guide for completing a specific task;
• a reference for exact metadata, commands, and structure;
• an explanation for understanding the design and trade-offs.

One source file stays authoritative. The four views are projections.

Why one giant skill document is not enough

Diataxis starts from a useful distinction: documentation should serve the user’s mode, not merely describe the software’s shape.

A new user following a tutorial wants a safe path through one representative run. They do not want an exhaustive field listing.

An experienced operator fixing a concrete problem wants a short decision path and relevant failure modes. They do not want the conceptual history first.

A tool or agent consulting reference material wants exact names, requirements, and commands. It should not infer those from narrative prose.

A maintainer deciding whether to adopt the skill wants to understand why the workflow exists and which trade-offs it encodes.

Putting all four in one document does not make it four kinds of documentation. It makes one long document with competing reading orders.

This matters more for agent skills than for ordinary library docs. A skill is both documentation and executable context. Extra prose costs tokens every time the skill is loaded. Rewriting the runtime file to optimize for human browsing can make agent execution worse; optimizing only for runtime brevity makes the skill hard to discover and audit.

The right boundary is a compact canonical execution contract plus generated human-facing views.

The generator is deliberately boring

The implementation does not ask a model to rewrite every skill. It parses Markdown.

For each SKILL.md, the generator reads:

• YAML frontmatter;
• headings and section bodies;
• fenced code blocks;
• optional metadata from the skill index;
• links back to related files.

It then selects and rearranges source sections according to the target surface. Tutorial generation prefers workflow sections and runnable examples. The how-to surface emphasizes decisions, anti-patterns, and troubleshooting. Reference exposes metadata and command blocks. Explanation pulls conceptual sections such as background and “why this matters.”

Batch mode discovers all local skills, writes four files per skill, and produces a single index linking every surface. The first full run generated 168 documents from 42 skills.

Determinism is the important property. The output can be regenerated, diffed, tested, and traced to its source. There is no hidden paraphrase step where a model can quietly change an operational rule.

That restraint also keeps ownership clear:

skills/<name>/SKILL.md                 canonical runtime contract
knowledge/skills/diataxis/<name>/      generated reading surfaces
  tutorial.md
  how-to.md
  reference.md
  explanation.md

If a rule is wrong, fix the skill. Do not patch four generated copies and wait for them to drift apart.

Generated documentation still has path semantics

The first batch exposed a subtle bug: relative links copied from a skill were valid relative to the source file, but broken relative to the generated output directory.

A source link like this:

[Related workflow](../other-skill/SKILL.md)

cannot be copied byte-for-byte into a document several directories deeper. The text survives. The destination changes.

The fix was to resolve each relative target against the source skill, then compute a new relative path from the generated document. External URLs, absolute paths, and fragment-only links stay untouched.

That is a small implementation detail with a broader lesson: documentation generation is not only text transformation. Links, anchors, include paths, and provenance all have location-dependent meaning. A generator that preserves words while breaking navigation has not preserved the document.

We added regression coverage for link rebasing rather than relying on a successful batch run. “Generated 168 files” is an output count, not a correctness proof.

What this does not solve

The generator does not create missing knowledge.

If the source skill has no useful rationale, the explanation surface will be thin. If its procedure is ambiguous, rearranging headings does not make the procedure precise. If one source section mixes tutorial prose, reference fields, and three unrelated examples, deterministic extraction can still produce rough output.

We are also not maintaining four handcrafted documentation trees. That would replace one discoverability problem with a synchronization problem.

The generated views are useful because they expose source quality. A weak tutorial often means the canonical skill lacks a concrete first run. A weak reference often means important requirements exist only in prose. The projection turns those gaps into visible defects without pretending to fill them automatically.

Nor is this an interactive code-tour system. There is no execution-trace integration yet, no adaptive path based on reader behavior, and no claim that generated structure proves the skill works. Runtime behavior still needs tests and real executions.

The deeper pattern: project, do not duplicate

Documentation often splits because different audiences need different views. The usual response is to create separate files and rely on maintainers to keep them synchronized. That works until it does not: one command changes, one guide stays stale, and the most approachable page becomes the least trustworthy one.

A better pattern is to identify the smallest authoritative artifact and generate audience-specific projections from it.

This applies beyond agent skills:

• CLI metadata can produce reference tables while tutorials remain curated;
• API schemas can produce endpoint reference while explanations link to design decisions;
• operational runbooks can produce incident checklists and audit-oriented control maps;
• test manifests can produce compatibility matrices without duplicating supported-version data.

The source does not need to be pleasant for every reader. It needs to be precise enough that each projection can serve one reader well.

For agent systems, that boundary is especially valuable. The runtime context stays compact and operational. Humans get navigable documentation. Both remain tied to the same source and the same git history.

One skill file should not pretend to be four documents at once. It should be one good execution contract that can reliably become four useful views.