phx-document
'Use when asked to document Elixir code: add or fill in @moduledoc and
Install
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/targets/amp/skills/phx-document
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Document
Generate documentation for newly implemented features.
Usage
phx-document .claude/plans/magic-link-auth/plan.md
phx-document magic link authentication
phx-document # Auto-detect from recent plan
Iron Laws
- Never remove existing documentation — Existing docs may reflect design intent that isn't obvious from code alone; update rather than replace
- @moduledoc on every public module — Undocumented modules accumulate quickly and create onboarding friction for new team members
- ADRs capture the "why", not the "what" — Code shows what was built; ADRs explain why this approach was chosen over alternatives
- Match @doc to function's public API — Document parameters, return values, and edge cases; callers shouldn't need to read the implementation
- DO NOT add @doc to untested code — documentation implies a stable contract; document only after tests confirm the function behaves as described
What Gets Documented
| Output | Description |
|---|---|
@moduledoc |
For new modules missing documentation |
@doc |
For public functions without docs |
| README section | For user-facing features |
| ADR | For significant architectural decisions |
Workflow
Step 0: Pre-check (avoid no-op runs)
Run git diff --name-only HEAD~5 | grep '\.ex$' | head -20 to check for new .ex files.
If no new .ex files were added (only modifications), skip the full
audit and report: "No new modules — documentation coverage unchanged."
A full audit of unchanged coverage produces nothing to add.
- Identify new modules from recent commits or plan file
- Check documentation coverage (
@moduledoc,@doc) - Generate missing docs using templates
- Add README section if user-facing feature
- Create ADR if architectural decision was made
- Write report to
.claude/plans/{slug}/reviews/{feature}-docs.md
When to Generate ADRs
| Trigger | Create ADR |
|---|---|
| New external dependency | Yes |
| New database table | Maybe (if schema non-obvious) |
| New OTP process | Yes (explain why process needed) |
| New context | Maybe (if boundaries non-obvious) |
| New auth mechanism | Yes |
| Performance optimization | Yes |
Integration with Workflow
phx-plan → phx-work → phx-review
↓
phx-document ← YOU ARE HERE (optional, suggested after review passes)
References
references/doc-templates.md— @moduledoc, @doc, README, ADR templatesreferences/output-format.md— Documentation report formatreferences/doc-best-practices.md— Elixir documentation best practicesreferences/documentation-patterns.md— Detailed documentation patterns
Files (claude-elixir-phoenix)
-
references
-
doc-best-practices.md 600 B
Loading… -
doc-templates.md 1.1 KB
Loading… -
documentation-patterns.md 6.9 KB
Loading… -
output-format.md 803 B
Loading…
-
-
SKILL.md 2.9 KB
--- name: phx-document description: 'Use when asked to document Elixir code: add or fill in @moduledoc and @doc for modules and functions. Documents tested code only; may add a README section or ADR. Not for docs lookup or audits.' --- # Document Generate documentation for newly implemented features. ## Usage ``` phx-document .claude/plans/magic-link-auth/plan.md phx-document magic link authentication phx-document # Auto-detect from recent plan ``` ## Iron Laws 1. **Never remove existing documentation** — Existing docs may reflect design intent that isn't obvious from code alone; update rather than replace 2. **@moduledoc on every public module** — Undocumented modules accumulate quickly and create onboarding friction for new team members 3. **ADRs capture the "why", not the "what"** — Code shows what was built; ADRs explain why this approach was chosen over alternatives 4. **Match @doc to function's public API** — Document parameters, return values, and edge cases; callers shouldn't need to read the implementation 5. **DO NOT add @doc to untested code** — documentation implies a stable contract; document only after tests confirm the function behaves as described ## What Gets Documented | Output | Description | |--------|-------------| | `@moduledoc` | For new modules missing documentation | | `@doc` | For public functions without docs | | README section | For user-facing features | | ADR | For significant architectural decisions | ## Workflow ### Step 0: Pre-check (avoid no-op runs) Run `git diff --name-only HEAD~5 | grep '\.ex$' | head -20` to check for new `.ex` files. If no new `.ex` files were added (only modifications), skip the full audit and report: "No new modules — documentation coverage unchanged." A full audit of unchanged coverage produces nothing to add. 1. **Identify** new modules from recent commits or plan file 2. **Check** documentation coverage (`@moduledoc`, `@doc`) 3. **Generate** missing docs using templates 4. **Add** README section if user-facing feature 5. **Create** ADR if architectural decision was made 6. **Write** report to `.claude/plans/{slug}/reviews/{feature}-docs.md` ## When to Generate ADRs | Trigger | Create ADR | |---------|-----------| | New external dependency | Yes | | New database table | Maybe (if schema non-obvious) | | New OTP process | Yes (explain why process needed) | | New context | Maybe (if boundaries non-obvious) | | New auth mechanism | Yes | | Performance optimization | Yes | ## Integration with Workflow ```text phx-plan → phx-work → phx-review ↓ phx-document ← YOU ARE HERE (optional, suggested after review passes) ``` ## References - `references/doc-templates.md` — @moduledoc, @doc, README, ADR templates - `references/output-format.md` — Documentation report format - `references/doc-best-practices.md` — Elixir documentation best practices - `references/documentation-patterns.md` — Detailed documentation patterns
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.