Generates and validates project documentation: READMEs, ADRs, changelogs, ARCHITECTURE.md, and code documentation. Use when creating, updating, or reviewing any non-code markdown artifact, README file, architecture decision record, ARCHITECTURE document, CHANGELOG entry, or code documentation (docstrings, XML docs, TSDoc). Activates for: (1) scaffolding README, CHANGELOG, ADR, CONTRIBUTING, ARCHITECTURE, or SECURITY files; (2) writing or reviewing doc comments on exported APIs; (3) auditing d...
Scanned 9/19/2026
Install to Claude Code
Skills Directorynpx -y skills add bsamiee/Parametric_Portal --skill docgen --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Docgen?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/bsamiee-docgen)More formats (shields.io, HTML) on the badges page.
---
name: docgen
description: >-
Generates and validates project documentation: READMEs, ADRs, changelogs,
ARCHITECTURE.md, and code documentation. Use when creating, updating, or
reviewing any non-code markdown artifact, README file, architecture decision
record, ARCHITECTURE document, CHANGELOG entry, or code documentation
(docstrings, XML docs, TSDoc). Activates for: (1) scaffolding README,
CHANGELOG, ADR, CONTRIBUTING, ARCHITECTURE, or SECURITY files; (2) writing
or reviewing doc comments on exported APIs; (3) auditing documentation
coverage or staleness; (4) generating release notes from commit history.
metadata:
token_estimates:
entry_point: 2800
full_load: 12000
max_load: 24000
---
# [H1][DOCGEN]
>**Dictum:** *Documentation is a typed contract between author and reader.*
<br>
Single authority on documentation structure, content requirements, and generation workflow. Routes to task-specific references by document type. Code examples in references align with csharp-standards, python-standards, and ts-standards — those skills remain authority on code discipline; this skill governs documentation discipline.
---
## [1][LOAD_SEQUENCE]
>**Dictum:** *Foundation references apply to every documentation task.*
<br>
**Step 1 — Foundation (always load first)**
| [INDEX] | [REFERENCE] | [FOCUS] |
| :-----: | :-------------- | -------------------------------- |
| [1] | `validation.md` | Compliance checklists per type |
| [2] | `patterns.md` | Documentation anti-pattern codex |
**Step 2 — Task-specific (load per routing table)**
| [INDEX] | [REFERENCE] | [LOAD_WHEN] |
| :-----: | :-------------------- | ---------------------------------- |
| [3] | `readme-gen.md` | README creation or update |
| [4] | `adr.md` | Architecture decision recording |
| [5] | `code-docs.md` | Code documentation (any language) |
| [6] | `changelog-gen.md` | Changelog or release notes |
| [7] | `contributing-gen.md` | CONTRIBUTING.md creation |
| [8] | `architecture-gen.md` | ARCHITECTURE.md creation or update |
**Step 3 — Template (scaffolding only)**
| [INDEX] | [TEMPLATE] | [ARCHETYPE] |
| :-----: | :------------------------- | :----------: |
| [9] | `readme.template.md` | README |
| [10] | `adr.template.md` | ADR |
| [11] | `architecture.template.md` | ARCHITECTURE |
---
## [2][CONTRACTS]
>**Dictum:** *Structural invariants constrain all documentation.*
<br>
**Content discipline**
- **Documentation completes type signature** — encode intent, constraints, failure semantics, domain invariants. Never restate what types and names already communicate.
- **Every document targets one Diátaxis quadrant:** Tutorial (learning), How-To (task), Reference (information), Explanation (understanding). Mixing quadrants produces documents that serve no audience well.
**Generation discipline**
- **Exploration before generation:** Read project structure, dependencies, existing documentation before producing new content. Generated documentation contradicting existing artifacts is worse than no documentation.
- **Code examples are compilable/runnable** — never pseudocode, never truncated. For libraries: importable. For services: `curl` with expected response. For CLIs: exact invocation with output.
- **Audience-first structure:** Organize content by reader need, not by implementation topology.
**Density discipline**
- **Standards docs** (`docs/standards/*.md`): canonical truth about document types. 125-200 LOC.
- **Skill references** (`references/*.md`): generation-specific instructions. <250 LOC each.
- **Templates** (`templates/*.md`): structural skeletons with placeholders, guidance, and checklists. <125 LOC each.
---
## [3][ROUTING]
>**Dictum:** *Task type determines reference loading.*
<br>
| [INDEX] | [TASK] | [REFERENCES] | [TEMPLATE] | [STANDARDS_DOC] |
| :-----: | ------------------------- | ------------------- | ------------------------ | ------------------------------- |
| [1] | **README creation** | readme-gen.md | readme.template.md | readme-standards.md |
| [2] | **README update** | readme-gen.md | — | readme-standards.md |
| [3] | **ADR creation** | adr.md | adr.template.md | adr-standards.md |
| [4] | **ADR review** | adr.md | — | adr-standards.md |
| [5] | **Code documentation** | code-docs.md | — | code-documentation-standards.md |
| [6] | **CONTRIBUTING creation** | contributing-gen.md | — | — |
| [7] | **ARCHITECTURE creation** | architecture-gen.md | architecture.template.md | architecture-standards.md |
| [8] | **ARCHITECTURE update** | architecture-gen.md | — | architecture-standards.md |
| [9] | **Changelog entry** | changelog-gen.md | — | changelog-standards.md |
| [10] | **Release notes** | changelog-gen.md | — | changelog-standards.md |
| [11] | **Doc validation/audit** | validation.md | — | (all applicable) |
---
## [4][DECISION_TREES]
>**Dictum:** *Branching tables route ambiguous tasks.*
<br>
**Document type selection:**
| [INDEX] | [SIGNAL] | [DOCUMENT_TYPE] |
| :-----: | -------------------------------------------- | :--------------: |
| [1] | New project, no README exists | README |
| [2] | New directory with 2+ docs, no index | README (hub) |
| [3] | Monorepo package missing documentation | README (package) |
| [4] | Architectural choice with alternatives | ADR |
| [5] | Version release, feature completion | Changelog |
| [6] | New/modified exported API surface | Code-Doc |
| [7] | New project accepting external contributions | CONTRIBUTING |
| [8] | System with 10k+ LOC needing structural docs | ARCHITECTURE |
| [9] | Existing documentation accuracy concern | Validation |
**README scope routing:**
| [INDEX] | [CONTEXT] | [SCOPE] | [REFERENCE_SECTION] |
| :-----: | ------------------------------------------- | :---------------: | ------------------------ |
| [1] | Project root, full project documentation | Project root | readme-gen.md §3.1 row 1 |
| [2] | `packages/*` or `apps/*` in monorepo | Package/workspace | readme-gen.md §3.4 |
| [3] | `src/modules/*` or bounded context boundary | Module/feature | readme-gen.md §3.1 row 3 |
| [4] | `docs/` or directory with child `.md` files | Directory hub | readme-gen.md §3.3 |
**README audience routing:**
| [INDEX] | [AUDIENCE] | [SECTION_DEPTH] | [EMPHASIS] |
| :-----: | --------------- | ---------------------------- | -------------------- |
| [1] | **Evaluator** | Title, Description, Badges | Problem/solution fit |
| [2] | **Adopter** | + Install, Usage, License | Time to first value |
| [3] | **Contributor** | + Architecture, Contributing | Orientation velocity |
**Code doc language routing:**
| [INDEX] | [LANGUAGE] | [FORMAT] | [EFFECT_TYPE_DOCS] |
| :-----: | -------------- | ----------------- | --------------------------------------- |
| [1] | **C#** | XML Documentation | `Fin<T>` success/failure in `<returns>` |
| [2] | **Python** | Google Style | `Result[T,E]` in Returns section |
| [3] | **TypeScript** | TSDoc | `Effect<A,E>` in `@returns` tag |
---
## [5][ANTI_PATTERNS]
>**Dictum:** *Named violations enable precise correction.*
<br>
Summary table — full examples in `patterns.md`.
| [INDEX] | [PATTERN] | [SYMPTOM] | [CORRECTION] |
| :-----: | ------------------ | ------------------------------------------------ | ------------------------------------------- |
| [1] | TROPHY_README | Lists every file; no architecture explanation | Audience-tiered progressive disclosure |
| [2] | COMMIT_CHANGELOG | Git log dumped as changelog entries | User-facing language grouped by category |
| [3] | WALL_OF_TEXT_ADR | Context section narrates history | Bullet-point facts with explicit unknowns |
| [4] | PARAMETER_NOISE | `@param name` repeats "the name" | State constraint, range, or semantic origin |
| [5] | STALE_DOCS | Documents removed/changed functionality | Couple doc updates to code change workflow |
| [6] | PSEUDOCODE_EXAMPLE | Code examples that won't compile/run | Extractable, testable examples only |
| [7] | AUDIENCE_MIXING | Single doc targeting evaluators and contributors | One Diátaxis quadrant per document |
| [8] | TYPE_RESTATING | Comment says "Returns string" on `-> str` | Document what types cannot express |
---
## [6][VALIDATION]
>**Dictum:** *Gates prevent documentation debt.*
<br>
[VERIFY]: Per-task completion — select checklist from `validation.md` matching document type.
[IMPORTANT]:
1. [ALWAYS] Load `validation.md` before marking any documentation task complete.
2. [ALWAYS] Verify code examples compile/run in the target language.
[CRITICAL]:
- [NEVER] Skip negative consequence documentation in ADRs.
- [NEVER] Ship a README without a runnable Usage example.
- [NEVER] Document code by restating type signatures.
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
