adaptive-enforcement-lab/documentation-as-skills

Documentation as Skills

When to Use This Skill

Engineering knowledge that lives only on a documentation site competes with whatever an AI agent produces from general training data.

The agent answers in seconds without leaving the editor. The docs require someone to feel uncertain, go looking, and read. In that race, correct-but-unread documentation loses.

Compiling docs into skills removes the race. The patterns are present in the agent's context when code is written, carrying the specific decisions a team has already made rather than a plausible generic default.

The trade-off is that generated skills are only as good as their source. A vague page compiles into a vague skill, delivered with more authority and less friction than the page had. This pipeline is a multiplier on documentation quality, not a substitute for it.

Prerequisites

• A documentation tree with consistent structure, since this pipeline keys on index.md files and YAML frontmatter
• YAML frontmatter carrying at minimum title and description on every page intended to become a skill
• Go 1.26 or later to build the generator
• A GitHub App (or equivalent machine identity) if regeneration runs in CI and must open pull requests

When to Apply

| Situation | Use this pattern? | | --- | --- | | Documentation already structured with consistent frontmatter | Yes, extraction is nearly free | | Patterns are team-specific and differ from general practice | Yes, this is the highest-value case | | Documentation is prose-heavy with few conventional headings | Restructure first, or extraction will produce thin skills | | Content changes several times per day | Reconsider, since regeneration churn may outweigh benefit | | Fewer than roughly ten documents | No, hand-author the skills instead |

Implementation

The pipeline has four stages. Each is documented in detail on its own page.

graph LR
    A[docs/**/index.md] --> B[Parse frontmatter<br/>+ sections]
    B --> C[Map to skill<br/>components]
    C --> D[Validate]
    D --> E[Render SKILL.md<br/>+ side files]
    E --> F[Write marketplace<br/>+ plugin manifests]

Extraction Pipeline: How documents are discovered, which are skipped, and how a path becomes a plugin and skill name.

Skill Anatomy: What a generated skill directory contains, how section mapping works, and the thresholds that decide which optional files appear.

Marketplace and Versioning: How plugin manifests and the marketplace catalog are generated, and how release-please drives version numbers.

CI Automation: Triggering regeneration from a documentation change, authenticating with a GitHub App, and the commit-versus-PR decision.

Key Principles

One document, one skill. Each index.md under a mapped category directory becomes exactly one skill. Sibling pages are supporting material, not separate skills. This keeps the skill count proportional to concepts rather than files.

Frontmatter is the routing contract. The description field is the only text the agent sees when deciding whether a skill applies. It is copied verbatim into the generated skill, which makes it the highest-leverage field in the entire source document.

Structure carries meaning. Section headings are matched against known component buckets: prerequisites, implementation, anti-patterns, troubleshooting. Documents written with conventional headings extract cleanly; documents with idiosyncratic ones produce thin skills.

Generation is idempotent. Running the generator twice against unchanged docs produces byte-identical output. This makes work avoidance in CI trivial: if git status is clean, there is nothing to publish.

Validation is advisory, not blocking. A skill that fails validation is still written, and the finding is surfaced. Generation of 116 good skills should not be blocked by one document with a short description.

Techniques

Anti-Patterns

Hand-editing generated skills. Any change to a file under the generated plugin tree is destroyed on the next run. Fix the source document instead. Marking the output directory as generated in code review tooling prevents well-meaning edits.

Skipping the description field. A missing or vague description produces a skill the agent cannot route to. It will exist, consume space in the catalog, and never load.

Blocking generation on validation failure. One malformed document should never prevent the other hundred-plus skills from publishing. Report findings, write the output, fix the source.

Treating skill count as a quality metric. More skills is not better. Skills that never load are noise; the number worth tracking is how often each one is actually used.

---

Related: Release Pipelines · Versioned Documentation · Go CLI Architecture

Anti-Patterns to Avoid

Hand-editing generated skills. Any change to a file under the generated plugin tree is destroyed on the next run. Fix the source document instead. Marking the output directory as generated in code review tooling prevents well-meaning edits.

Skipping the description field. A missing or vague description produces a skill the agent cannot route to. It will exist, consume space in the catalog, and never load.

Blocking generation on validation failure. One malformed document should never prevent the other hundred-plus skills from publishing. Report findings, write the output, fix the source.

Treating skill count as a quality metric. More skills is not better. Skills that never load are noise; the number worth tracking is how often each one is actually used.

---

Related: Release Pipelines · Versioned Documentation · Go CLI Architecture

References

• Source Documentation
• AEL Build