elixir-writing-docs — Claude Code skill: what it does, how to install
elixir-writing-docs guides writing Elixir documentation using @moduledoc, @doc, @typedoc, doctests, and ExDoc metadata in .ex source files.
Apache-2.0 106 installs ★ 89 updated 2026-09-15
npx skills add existential-birds/beagle --skill elixir-writing-docs -a claude-codeWhat elixir-writing-docs does
This skill teaches coding assistants how to structure Elixir documentation for ExDoc and mix docs. It enforces the first-line summary rule, ensuring the opening paragraph functions as a clear standalone description before deeper details begin.
The guide lays out module anatomy with second-level markdown headers like ## Examples and ## Configuration. It dictates placing @spec definitions between @doc and def, formatting keyword list options under ## Options, and using @typedoc on custom or opaque types.
Side-effecting functions must avoid runnable doctests. Pure functions, by contrast, require executable iex> doctest blocks.
What it helps with
- format @moduledoc and @doc summaries tailored for ExDoc extraction
- structure function option lists under ## Options headers
- hide internal helpers and protocol implementations with @doc false
- document opaque types and behaviours with callback lists
Example prompts for the agent
- Write @moduledoc and doctests for my inventory cache module
- Add @doc with options and @spec to this payment charge function
- Mark this deprecated Elixir function with @doc deprecated: metadata
How to install elixir-writing-docs
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-writing-docs -a claude-code2Manually: put the files in place
~/.claude/skills/elixir-writing-docs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/elixir-writing-docs/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-writing-docs -a codex2Manually: put the files in place
.agents/skills/elixir-writing-docs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-writing-docs -a cursor2Manually: put the files in place
.cursor/skills/elixir-writing-docs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install existential-birds/beagle plugins/beagle-elixir/skills/elixir-writing-docs2Manually: put the files in place
.github/skills/elixir-writing-docs/SKILL.md1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-writing-docs -a gemini-cli2Platform CLI
gemini skills install https://github.com/existential-birds/beagle --path plugins/beagle-elixir/skills/elixir-writing-docsManually: put the files in place
.devin/skills/elixir-writing-docs/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill elixir-writing-docs -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about elixir-writing-docs
How do I install elixir-writing-docs in Claude Code?
Run npx skills add existential-birds/beagle --skill elixir-writing-docs -a claude-code.
What does elixir-writing-docs do?
It guides formatting Elixir module and function documentation, ensuring correct heading levels, doctest syntax, and ExDoc metadata.
When does the skill suggest using @doc false?
Use @doc false on internal helper functions, callback implementations, and protocol implementations to keep them out of public ExDoc output.
Source text
SKILL.md · Apache-2.0
---
name: elixir-writing-docs
description: Guides writing Elixir documentation with @moduledoc, @doc, @typedoc, doctests, cross-references, and metadata. Use when adding or improving documentation in .ex files.
---
# Elixir Writing Docs
## Quick Reference
| Topic | Reference |
|-------|-----------|
| Doctests: syntax, gotchas, when to use | [references/doctests.md](references/doctests.md) |
| Cross-references and linking syntax | [references/cross-references.md](references/cross-references.md) |
| Admonitions, formatting, tabs | [references/admonitions-and-formatting.md](references/admonitions-and-formatting.md) |
## First-Line Summary Rule
ExDoc and tools like `mix docs` extract the first paragraph of `@moduledoc` and `@doc` as a summary. Keep the opening line concise and self-contained.
```elixir
# GOOD - first line works as a standalone summary
@moduledoc """
Handles payment processing through Stripe and local ledger reconciliation.
Wraps the Stripe API client and ensures each charge is recorded in the
local ledger before returning a confirmation to the caller.
"""
# BAD - first line is vague, forces reader to continue
@moduledoc """
This module contains various functions related to payments.
It uses Stripe and also updates the ledger.
"""
```
The same rule applies to `@doc`:
```elixir
# GOOD
@doc """
Charges a customer's default payment method for the given amount in cents.
Returns `{:ok, charge}` on success or `{:error, reason}` when the payment
gateway rejects the request.
"""
# BAD
@doc """
This function is used to charge a customer.
"""
```
## @moduledoc Structure
A well-structured `@moduledoc` follows this pattern:
```elixir
defmodule MyApp.Inventory do
@moduledoc """
Tracks warehouse stock levels and triggers replenishment orders.
This module maintains an ETS-backed cache of current quantities and
exposes functions for atomic stock adjustments. It is designed to be
started under a supervisor and will restore state from the database
on init.
## Examples
iex> {:ok, pid} = MyApp.Inventory.start_link(warehouse: :east)
iex> MyApp.Inventory.current_stock(pid, "SKU-1042")
{:ok, 350}
## Configuration
Expects the following in `config/runtime.exs`:
config :my_app, MyApp.Inventory,
repo: MyApp.Repo,
low_stock_threshold: 50
"""
end
```
**Key points:**
- First paragraph is the summary (one to two sentences).
- `## Examples` shows realistic usage. Use doctests when the example is runnable.
- `## Configuration` documents required config keys. Omit this section if the module takes no config.
- Use second-level headings (`##`) only. First-level (`#`) is reserved for the module name in ExDoc output.
### Documenting Behaviour Modules
When defining a behaviour, document the expected callbacks:
```elixir
defmodule MyApp.PaymentGateway do
@moduledoc """
Behaviour for payment gateway integrations.
Implementations must handle charging, refunding, and status checks.
See `MyApp.PaymentGateway.Stripe` for a reference implementation.
## Callbacks
* `charge/2` - Initiate a charge for a given amount
* `refund/2` - Refund a previously completed charge
* `status/1` - Check the status of a transaction
"""
@callback charge(amount :: pos_integer(), currency :: atom()) ::
{:ok, transaction_id :: String.t()} | {:error, term()}
@callback refund(transaction_id :: String.t(), amount :: pos_integer()) ::
:ok | {:error, term()}
@callback status(transaction_id :: String.t()) ::
{:pending | :completed | :failed, map()}
end
```
## @doc Structure
```elixir
@doc """
Reserves the given quantity of an item, decrementing available stock.
Returns `{:ok, reservation_id}` when stock is available, or
`{:error, :insufficient_stock}` when the requested quantity exceeds
what is on hand.
## Examples
iex> MyApp.Inventory.reserve("SKU-1042", 5)
{:ok, "res_abc123"}
iex> MyApp.Inventory.reserve("SKU-9999", 1)
{:error, :not_found}
## Options
* `:warehouse` - Target warehouse atom. Defaults to `:primary`.
* `:timeout` - Timeout in milliseconds. Defaults to `5_000`.
"""
@spec reserve(String.t(), pos_integer(), keyword()) ::
{:ok, String.t()} | {:error, :insufficient_stock | :not_found}
def reserve(sku, quantity, opts \\ []) do
# ...
end
```
**Guidelines:**
- State what the function does, then what it returns.
- Document each option in a bulleted `## Options` section when the function accepts a keyword list.
- Place `@spec` between `@doc` and `def`. This is the conventional ordering.
- Include doctests for pure functions. Skip them for side-effecting functions (see [references/doctests.md](references/doctests.md)).
## @typedoc
Document custom types defined with `@type` or `@opaque`:
```elixir
@typedoc """
A positive integer representing an amount in the smallest currency unit (e.g., cents).
"""
@type amount :: pos_integer()
@typedoc """
Reservation status returned by `status/1`.
* `:held` - Stock is reserved but not yet shipped
* `:released` - Reservation was cancelled and stock restored
* `:fulfilled` - Items have shipped
"""
@type reservation_status :: :held | :released | :fulfilled
@typedoc """
Opaque handle returned by `connect/1`. Do not pattern-match on this value.
"""
@opaque connection :: %__MODULE__{socket: port(), buffer: binary()}
```
For `@opaque` types, the `@typedoc` is especially important because callers cannot inspect the structure.
## Metadata
### @doc since and @doc deprecated
```elixir
@doc since: "1.3.0"
@doc """
Transfers stock between two warehouses.
"""
def transfer(from, to, sku, quantity), do: # ...
@doc deprecated: "Use transfer/4 instead"
@doc """
Moves items between locations. Deprecated in favor of `transfer/4`
which supports cross-region transfers.
"""
def move_stock(from, to, sku, quantity), do: # ...
```
You can combine metadata and the docstring in one attribute:
```elixir
@doc since: "2.0.0", deprecated: "Use bulk_reserve/2 instead"
@doc """
Reserves multiple items in a single call.
"""
def batch_reserve(items), do: # ...
```
`@moduledoc since:` works the same way for modules:
```elixir
@moduledoc since: "1.2.0"
@moduledoc """
Handles webhook signature verification for Stripe events.
"""
```
## When to Use @doc false / @moduledoc false
Suppress documentation when the module or function is not part of the public API:
```elixir
# Private implementation module — internal to the application
defmodule MyApp.Inventory.StockCache do
@moduledoc false
# ...
end
# Protocol implementation — documented at the protocol level
defimpl String.Chars, for: MyApp.Money do
@moduledoc false
# ...
end
# Callback implementation — documented at the behaviour level
@doc false
def handle_info(:refresh, state) do
# ...
end
# Helper used only inside the module
@doc false
def do_format(value), do: # ...
```
**Do NOT use `@doc false` on genuinely public functions.** If a function is exported and callers depend on it, document it. If it should not be called externally, make it private with `defp`.
## Documentation vs Code Comments
| | Documentation (`@moduledoc`, `@doc`) | Code Comments (`#`) |
|---|---|---|
| **Audience** | Users of your API | Developers reading source |
| **Purpose** | Contract: what it does, what it returns | Why a particular implementation choice was made |
| **Rendered** | Yes, by ExDoc in HTML/epub | No, visible only in source |
| **Required** | All public modules and functions | Only where code intent is non-obvious |
```elixir
@doc """
Validates that the given coupon code is active and has remaining uses.
"""
@spec validate_coupon(String.t()) :: {:ok, Coupon.t()} | {:error, :expired | :exhausted}
def validate_coupon(code) do
# We query the read replica here to avoid adding load to the
# primary during high-traffic discount events.
Repo.replica().get_by(Coupon, code: code)
|> check_expiry()
|> check_remaining_uses()
end
```
The `@doc` tells the caller what `validate_coupon/1` does and returns. The inline comment explains an implementation decision that would otherwise be surprising.
## Completing documentation (gates)
Finish with these **sequenced** checks. Skip a step when it does not apply.
1. **Doctests added or changed?** Run the project’s doctest verification (usually `mix test` for affected modules or the full suite). **Pass:** no doctest failures.
2. **Cross-references, backticks, or `m:` links added or edited?** Run `mix docs`. **Pass:** the command completes; resolve ExDoc warnings about missing modules, callbacks, or bad links.
3. **New or changed public API?** **Pass:** every exported `def` / `defmacro` has an intentional `@doc` or `@doc false`, and every public module has `@moduledoc` or `@moduledoc false`, consistent with your project’s policy.
## When to Load References
- Writing doctests or debugging doctest failures --> [references/doctests.md](references/doctests.md)
- Adding links between modules, functions, types --> [references/cross-references.md](references/cross-references.md)
- Using admonition blocks, tabs, or formatting in docs --> [references/admonitions-and-formatting.md](references/admonitions-and-formatting.md)
© existential-birds · Apache-2.0 · existential-birds/beagle