elixir-docs-review

What This Skill Does

The elixir-docs-review skill is a specialized auditing tool designed to maintain high-quality documentation standards across Elixir codebases. It systematically evaluates source files against ExDoc best practices, ensuring that @moduledoc and @doc annotations are informative, @spec definitions are accurate, and internal documentation consistency is maintained. By automating the review of module and function documentation, the skill helps developers adhere to community standards, such as including appropriate ## Examples, utilizing correct cross-referencing syntax (e.g., MyModule and function/2), and managing metadata like @since and @deprecated tags correctly. It intelligently distinguishes between public API requirements and internal implementation details, preventing unnecessary noise from private functions or protocol implementations.

Installation

To integrate this skill into your OpenClaw environment, execute the following command in your terminal: clawhub install openclaw/skills/skills/anderskev/elixir-docs-review Once installed, ensure your local repository includes the required reference files at references/doc-quality.md and references/spec-coverage.md, as these are critical for the agent to provide accurate, standard-compliant feedback.

Use Cases

• Auditing new feature pull requests to ensure all public APIs are documented and typed correctly.
• Refactoring legacy codebases to bring documentation up to modern ExDoc community standards.
• Validating that pure, deterministic functions include functional doctests for reliable documentation-as-test patterns.
• Checking for missing or outdated cross-references in large Elixir applications to improve discoverability.

Example Prompts

• "@elixir-docs-review please audit the lib/my_app/processor.ex file for missing specs and ensure the module documentation follows our standard pattern."
• "Review the handle_event/3 function in the current context; is the @doc description too generic, and are there any missing doctests?"
• "Scan this module for any broken cross-references to other modules and suggest improvements for the @moduledoc examples section."

Tips & Limitations

To maximize the efficiency of this skill, ensure that you provide the agent access to the relevant context files defined in the documentation-review protocol. Note that while this skill is highly effective at identifying structural issues and missing metadata, it relies on the provided references for semantic quality checks. It is optimized for Elixir's macro-based documentation system and should be used during the development or peer-review phase of the software lifecycle.