From amplify
Writes production-quality @moduledoc, @doc, and @typedoc annotations for Elixir modules, scaling structure to complexity with ExDoc conventions like cross-references, doctests, and return contracts. Use for thin or missing module docs.
npx claudepluginhub wunki/amplify --plugin ask-questions-if-underspecifiedThis skill uses the workspace's default tool permissions.
Write `@moduledoc`, `@doc`, and `@typedoc` annotations for Elixir modules. Doc shape follows module shape: scale documentation length and structure to match the module's complexity and public surface area. Delegate to the `tech-docs-writer` agent for the actual writing.
Generates @moduledoc and @doc annotations for Elixir modules, contexts, and schemas. Adds README sections and ADRs for new features after implementation.
Guides Elixir documentation with @moduledoc, @doc, @typedoc, doctests, cross-references, and metadata. Use when adding or improving docs in .ex files.
Provides templates and best practices for README files, API documentation, user guides, changelogs, inline code comments, and architecture docs.
Share bugs, ideas, or general feedback.
Write @moduledoc, @doc, and @typedoc annotations for Elixir modules. Doc shape follows module shape: scale documentation length and structure to match the module's complexity and public surface area. Delegate to the tech-docs-writer agent for the actual writing.
@moduledocDetermine which modules need documentation.
apps/*/lib/ instead of lib/:find lib/path/to/namespace -name '*.ex' | sort
Audit current doc quality. Check for missing @moduledoc, misuse of @moduledoc false, or thin/outdated docs:
# Find modules with no @moduledoc at all
while IFS= read -r -d '' f; do
grep -q '@moduledoc' "$f" || echo "NO MODULEDOC: $f"
done < <(find lib/path -name '*.ex' -print0)
# Find modules with @moduledoc false that might deserve docs
grep -rl '@moduledoc false' lib/path/to/namespace/
Categorize each module before writing. Respect the project's existing conventions for what gets documented. If the project already uses @moduledoc false consistently, follow that boundary. Otherwise, use these defaults:
*HTML view modules. Use @moduledoc false.Before writing any docs, understand the project:
@moduledoc blocks. Learn the project's voice and conventions from these.docs/ that should be cross-referenced.Documentation that contradicts the codebase is worse than no documentation.
Group modules by domain proximity (3-7 modules per agent). Modules that reference each other belong in the same group so the agent can read context.
Good groupings:
Read references/doc-standard.md now. Skip if the standard is already loaded in context. If the file is missing or empty, use the ExDoc conventions and quality bar sections below as the fallback standard.
For each group, launch a tech-docs-writer agent using the Agent tool (subagent_type: tech-docs-writer, run_in_background: true). Paste the full documentation standard into every agent prompt — the standard is designed to fit in a single prompt alongside the module source.
If the Agent tool is not available or background execution is not supported, process groups sequentially in the current session using the same prompt template and quality bar.
Agent prompt template:
Write documentation for these Elixir modules following the documentation
standard below. Read each module fully before writing. For context, also
read [list related modules the agent should understand].
Modules to document:
1. `path/to/module_a.ex` — one-line role description
2. `path/to/module_b.ex` — one-line role description
IMPORTANT:
- Do NOT change any code logic — only add or update documentation.
- Scale doc length to module complexity. Do not force structure on simple modules.
- Every public function needs at least one example.
- Use the `* :name` — description format for options.
- Use ExDoc cross-references, not plain backticks, for module/function refs.
[PASTE FULL DOC STANDARD FROM references/doc-standard.md]
After all agents complete:
mix compile --warnings-as-errors. If this fails due to pre-existing warnings unrelated to documentation changes, fall back to mix compile without --warnings-as-errors and note the pre-existing warnings separately.mix test test/my_app/billing/. For umbrella apps, run from the appropriate app directory.mix test only when requested or when scope is unclear.# Find documented modules missing examples (checks ## Example headers and iex> doctests)
while IFS= read -r -d '' f; do
has_moduledoc=$(grep -c '@moduledoc' "$f")
has_doc_false=$(grep -c '@moduledoc false' "$f")
has_example=$(grep -cE '(## Example|iex>)' "$f")
if [ "$has_moduledoc" -gt 0 ] && [ "$has_doc_false" -eq 0 ] && [ "$has_example" -eq 0 ]; then
echo "NO EXAMPLES: $f"
fi
done < <(find lib/path -name '*.ex' -print0)
Module.function/arity syntax, not plain backtick text.If modules still have quality gaps after one round of fixes, flag them to the user rather than retrying indefinitely.
Elixir documentation lives in BEAM files and is consumed three ways:
h Module or h Module.function prints plain text@doc on hoverWrite docs that work well in all three. Read references/doc-standard.md for the full set of ExDoc features. Skip if already loaded.
Summary of key features:
Pipeline.run/2, t:Context.t/0, c:GenServer.init/1 auto-link in hexdocs> #### Warning {: .warning} for callouts, gotchas, and audience scopingiex> examples in @doc run as ExUnit tests; use for pure functions only@moduledoc since:, @doc since:, @doc deprecated: rendered by ExDocAudience: An engineer who joined the team this week. Knows Elixir but not this codebase.
A first-time engineer opens any documented module and answers these in under 60 seconds:
Friction log test: Open 2-3 documented modules cold. Answer "Can I call this function safely?" using only the docs. If source code is needed, send the module back for a rewrite.
Docs rot: Docs must be updated in the same change that modifies behavior. Stale docs actively mislead.
@doc to trivial getters, delegations, or single-line wrappers.