reliquary/docs/workpad/brainstorm/2026-05-11-17-documentation-skill-adaptation.md

Brainstorm: should dirigent's documentation skill move to reliquary, and in what shape?

Source

../dirigent/.claude/skills/documentation.md — a flat markdown file (no folder, no frontmatter, no name:/description: header). 237 LOC. Defines a documentation philosophy + templates for CLAUDE.md, README.md, docs/architecture/, docs/api/.

First observation: it's not actually a skill

It's missing a frontmatter block. Claude Code skills need at minimum name: and description: so the runtime knows when to surface them. Without that, this file would never auto-activate — it's effectively a static reference document the user grep'd into manually. If we port it as-is, we'd be porting a doc, not a skill.

So the real question isn't "should we copy it" — it's "what concept inside it deserves to become a real skill, if any?"

What the file actually contains

Three loosely-related things bundled together:

1. A philosophy statement — "AI agents first, humans second", CLAUDE.md is lightweight, README is human-friendly, docs/ is deep-dive, cargo doc is API.
2. A folder structure prescription for monorepo / cargo-workspace Rust projects.
3. Four file templates — CLAUDE.md, README.md, architecture doc, API doc.

The philosophy is interesting. The folder structure is dirigent-specific (cargo packages, docs/architecture/, docs/api/). The templates are generic but opinionated.

Where each piece could go

The philosophy → a small skill, maybe

A skill called something like agent-readable-docs could be valuable. It would activate when the user asks to "document this package", "write a README", "add a CLAUDE.md", and would advise:

• Default reader is an LLM agent, not a human.
• CLAUDE.md = short, navigational, 20-50 lines.
• README.md = human-friendly with examples.
• Long-form goes in docs/.
• API specs go in docs/api/.

This is a real judgment-shape skill, not a template repository. It would compose with workpad (which owns docs/workpad/, not docs/architecture/).

The folder structure → not portable

The cargo-package layout in the file is dirigent-specific. Different projects (Python, Rust app, monorepo, library) want different shapes. Hardcoding "packages/<name>/CLAUDE.md" is wrong for anything that isn't a cargo workspace.

If we want this to be reusable, the skill must say "the user's project already has some layout — adapt" rather than "use this layout."

The templates → reference, not skill

Four templates is a small enough library that it could be a references/ folder inside an agent-readable-docs skill. The skill markdown points at them: "see references/claude-md-template.md for the structure."

Skills shouldn't paste 100 lines of template into their description — but they can host template files alongside and reference them.

Three options, ranked

Option 1 — Adapt as agent-readable-docs skill (recommended)

A new skill in plugins/g4b_ai/skills/agent-readable-docs/:

• SKILL.md — the philosophy + when to use which doc type. 60-80 LOC.
• references/CLAUDE-md.md — template (generic, not cargo-specific).
• references/README-md.md — template.
• references/architecture-doc.md — template.
• references/api-doc.md — template.

Composes with workpad ("workpad is for thinking-about-the-work; this skill is for documenting-the-work-itself"). Stays language-agnostic.

Risk: scope creep. "How to document code" is huge. Keep it tight — this skill is just about which file goes where and what shape, not about content quality.

Option 2 — Leave it in dirigent

It's dirigent-specific (cargo workspace, the project's own docs/architecture/ convention). Ports as a doc, not a skill. If you want to reuse it in dirigent forks, fine — but reliquary's plugins should be more generic.

Option 3 — Don't port, write fresh

The existing file has the right seed of an idea ("agent-readable docs first") but the wrong shape (templates inline, cargo-coupled). If you do port it, you'd rewrite ~80% anyway. Might be cleaner to write the skill fresh, taking only the philosophy paragraph as input.

In practice this is identical to Option 1 in outcome — the difference is whether you frame it as a port or a new skill.

Recommendation

Option 1, with these specific moves:

• Strip cargo-specific examples; replace with language-agnostic phrasing ("source root", not "src/lib.rs").
• Move all four templates into references/ rather than the skill body.
• Add a frontmatter description that triggers on "document this", "write a README", "add CLAUDE.md", "API docs", "architecture doc".
• Cross-reference workpad explicitly: workpad is for working about the code; this skill is for docs of the code.

Open question — overlap with workpad?

The workpad skill is very clear that it covers thinking-in-markdown (plans, reports, designs). Docs of the code (CLAUDE.md in a package, README.md, API specs) are deliberately out of workpad's scope — workpad owns docs/workpad/, not all of docs/.

An agent-readable-docs skill fills that gap cleanly. The two compose:

• workpad → where do my plans, reports, journals live?
• agent-readable-docs → where does my package's README + agent context + API spec live?

That's a healthy split. Worth doing.

What we'd skip

• The "Maintenance" section in the original (refactor → update CLAUDE files; new feature → update README). That's project-discipline advice, not skill content.
• The "Tips for Agents" section. Self-referential and adds noise.
• The hardcoded label Type: Library | Binary | UI | Service. Too narrow.