g4borg
1b5a7638d7
Add exploratory and design docs for porting dirigent skills to reliquary, including: - Explore port options for the gitea skill (in-plugin vs vendored) - Document activation mechanics across Claude Code and cross-tools - Include an orchestration comparison between dirigent and reliquary approaches - Add research on glob negation and flag-file activation patterns - Create uv-detection goals and skill-engines cross-tool reports - Provide a research plan for future porting work and risk notes
96 lines
5.6 KiB
Markdown
96 lines
5.6 KiB
Markdown
# 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.
|