К основному содержанию
скилл CX Codex

elixir-writing-docs — скилл для Claude Code

Скилл elixir-writing-docs для Claude Code оформляет документацию Elixir в файлах .ex: аннотации ExDoc, doctests и метаданные.

Apache-2.0 106 установок ★ 89 обновлён 2026-09-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add existential-birds/beagle --skill elixir-writing-docs -a claude-code
Открыть на GitHub

Что делает elixir-writing-docs

Скилл учит ассистента писать документацию в файлах .ex по стандартам ExDoc. Он заставляет выносить суть функции или модуля в самое первое предложение, потому что mix docs берёт первый абзац как краткое резюме для списков.

Внутри зафиксирована структура секций: заголовки второго уровня ## Examples и ## Options, порядок размещения спецификаций @spec строго между @doc и объявлением функции def, а также оформление колбэков для поведений. Приватный код, реализации протоколов и вспомогательные функции помечаются через @moduledoc false или @doc false, чтобы не засорять публичный API.

Если функция выполняет побочные эффекты, скилл требует отказаться от doctest и оставить обычный пример кода.

Какие задачи решает

  • сформулировать однострочные резюме для @moduledoc и @doc под генератор mix docs
  • разметить опции аргументов через секцию ## Options и типы параметров
  • скрыть внутренние функции и реализации протоколов с помощью @doc false
  • добавить doctests для чистых функций с проверкой через iex>

Примеры запросов агенту

  • Добавь модуль документации @moduledoc и примеры doctest в модуль MyApp.PaymentGateway
  • Оформи @doc и @spec для функции с ключевым списком параметров и секцией ## Options
  • Разметь депрекацию для старой функции с помощью @doc deprecated: "..."

Как установить elixir-writing-docs

1Через Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill elixir-writing-docs -a claude-code

2Вручную: положить файлы

~/.claude/skills/elixir-writing-docs/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/elixir-writing-docs/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об elixir-writing-docs

Как установить elixir-writing-docs в Claude Code?

Выполните команду npx skills add existential-birds/beagle --skill elixir-writing-docs -a claude-code.

Зачем нужен скилл elixir-writing-docs?

Он задаёт единый стандарт документирования кода на Elixir: от первой строки описания до doctests, пользовательских @typedoc и скрытия внутренних модулей.

Когда скилл рекомендует скрывать документацию через @doc false?

Атрибут @doc false применяется для вспомогательных приватных функций, реализаций поведений и протоколов, чтобы исключить их из сгенерированной справки ExDoc.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Тексты и документация» →
elixir Mindrally Задаёт агенту стиль работы с Elixir и Phoenix: функциональные паттерны, Ecto, LiveView, OTP. Используется в проектах на BEAM. CX Codex +1 881установок elixir-expert personamanagmentlayer Скилл elixir-expert для Claude Code по Elixir, OTP и Phoenix с примерами кода и разбором конкурентных систем. Помогает править GenServer и LiveView. CX Codex +1 194установок elixir-ecto-patterns TheBushidoCollective Скилл elixir-ecto-patterns для Claude Code подсказывает агенту, как писать код на Ecto: схемы, changesets, запросы, связи и транзакции. Описывает работу с базой в приложении на Elixir. CX Codex +1 121установок elixir-otp-patterns TheBushidoCollective Скилл elixir-otp-patterns помогает проектировать конкурентные отказоустойчивые сервисы на Elixir с опорой на проверенные архитектурные паттерны OTP. CX Codex +1 106установок elixir-engineer-guidelines-cursorrules-prompt-file PatrickJS Правило elixir-engineer-guidelines-cursorrules-prompt-file для Cursor задаёт контекст опытного Elixir-инженера и формат сообщений об изменениях. Учитывает стек проектов на Phoenix и связанные технологии. CX Codex +1 ★ 41 178звёзд репо elixir-pro Seth Hobson Субагент elixir-pro для Claude Code помогает проектировать OTP-приложения и писать код на Elixir. Подключается к задачам рефакторинга, Phoenix LiveView и оптимизации BEAM. CX Codex ★ 42 780звёзд репо

Из того же набора68

Весь набор →
pydantic-ai-model-integration Скилл pydantic-ai-model-integration помогает настроить провайдеров LLM, цепочки fallback, стриминг и лимиты токенов в библиотеке PydanticAI. CX Codex +1 120установок review-ai-writing Скилл review-ai-writing находит следы текстов нейросетей в документации, комментариях к коду, текстах коммитов и описаниях пулреквестов. Пригодится при проверке репозитория на канцелярский слог и роботизированные фразы. CX Codex +1 119установок wish-ssh-code-review Скилл wish-ssh-code-review проверяет код SSH-серверов на базе Go-библиотеки Charmbracelet Wish: порядок middleware, работу с PTY, ключи хоста и корректное завершение работы. CX Codex +1 119установок urlsession-code-review Скилл urlsession-code-review разбирает сетевой код на URLSession в iOS и macOS: статус-коды, кэш, таймауты и фоновые сессии. Находки идут с привязкой file:line. CX Codex +1 116установок elixir-security-review Скилл elixir-security-review проверяет код на Elixir на уязвимости: инъекции кода, переполнение таблицы атомов и утечки секретов. CX Codex +1 110установок elixir-performance-review Скилл elixir-performance-review для Claude Code проверяет код на Elixir и ищет узкие места в GenServer, памяти, конкурентности и базе данных. Находит причины просадки сервиса под нагрузкой. CX Codex +1 107установок rust-code-review Скилл rust-code-review для Claude Code проверяет Rust-код при ревью файлов .rs. Разбирает владение, заимствования, обработку ошибок, трейты и небезопасный код. CX Codex +1 104установок vercel-ai-sdk Справочник по Vercel AI SDK для сборки стриминговых чатов, вызова инструментов и обработки вложений. CX Codex +1 101установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой