# 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.