gh-bradleygolden-claude-marketplace-elixir-plugins-core/skills/hex-docs-search/README.md

Hex Docs Search Skill

A comprehensive skill for searching Elixir and Erlang package documentation using a cascading search strategy.

Overview

This skill helps Claude search for Hex package documentation intelligently by:

1. First checking local dependencies in deps/
2. Then checking previously fetched documentation and source in .hex-docs/ and .hex-packages/
3. Automatically fetching missing documentation or source code when needed (with version prompting)
4. Searching the codebase for real usage examples
5. Querying the hex.pm API for official docs
6. Falling back to web search if needed

Usage

This skill is automatically available when the core@elixir plugin is installed. Claude will use it when appropriate, for example:

User: "How do I use Phoenix.LiveView mount/3?"
User: "Show me Ecto.Query examples"
User: "What does Jason.decode!/1 do?"
User: "Research the Sobelow hex package"
User: "Learn about the Credo library"
User: "Understand how Ash Framework works"

How it Works

1. Local Dependencies Search (deps/)

Uses Grep and Glob tools to search installed packages for BOTH code and docs:

• Source code: Finds module definitions, function implementations, and @moduledoc/@doc annotations
• Generated docs: Checks for HTML documentation in deps/*/doc/ directories
• Provides full context from whichever source is most helpful

Advantage: Matches the exact version used in the project

2. Fetched Cache Search (.hex-docs/ and .hex-packages/)

Checks for previously fetched documentation and source code:

• Documentation: Searches .hex-docs/docs/hexpm/<package>/<version>/ for HTML docs
• Source code: Searches .hex-packages/<package>-<version>/ for unpacked source
• Uses same search patterns as deps/ directory

Advantage: Fast, offline-capable access to packages not in project dependencies

3. Progressive Fetch (NEW)

When packages aren't found locally, automatically fetches them:

• Version detection: Checks mix.lock, mix.exs, or hex.pm for version
• User prompting: Asks user to choose version when ambiguous (latest vs specific)
• Documentation first: Fetches HTML docs with mix hex.docs fetch to .hex-docs/
• Source if needed: Fetches source code with mix hex.package fetch --unpack to .hex-packages/
• Cached for future: All fetched content reusable in subsequent queries

Advantage: Builds a local knowledge base of documentation and source code over time

4. Codebase Usage Search

Searches the project's lib/ and test/ directories:

• Finds alias and import statements
• Locates function calls
• Shows real-world usage from your code

Advantage: Context-aware examples from your actual codebase

5. HexDocs Search API

Uses the HexDocs search API at https://search.hexdocs.pm/:

• Full-text search across documentation content
• Filters by package name and version
• Returns documentation excerpts with direct links
• Falls back to hex.pm API for package info

Advantage: Searches actual documentation content, not just package metadata

6. Web Search Fallback

Uses WebSearch with targeted queries:

• site:hexdocs.pm <package> <module> for specific docs
• General Elixir documentation search

Advantage: Finds community examples and guides

Examples

Example 1: Looking up a commonly used dependency

User: "How do I query with Ecto?"

Claude will:
1. Find deps/ecto/lib/ecto/query.ex
2. Search for "import Ecto.Query" in lib/
3. Show usage examples from the project
4. Read @moduledoc from the source

Example 2: Unknown package with progressive fetch

User: "What is the Timex library?"

Claude will:
1. Check deps/timex (not found)
2. Check .hex-docs/docs/hexpm/timex/ (not found)
3. Detect no version in project dependencies
4. Query hex.pm for latest version
5. Prompt: "Fetch latest (3.7.11) or specific version?"
6. User selects "Latest"
7. Fetch: HEX_HOME=.hex-docs mix hex.docs fetch timex 3.7.11
8. Search fetched HTML documentation
9. Present findings with link to cached docs
10. Suggest adding to .gitignore if not present

Future queries: Instant access to cached documentation

Example 3: Specific function lookup

User: "How does Jason.decode!/2 work?"

Claude will:
1. Find deps/jason/lib/jason.ex
2. Grep for "def decode!"
3. Show the @doc and implementation
4. Find usage in tests/

Requirements

• curl - For hex.pm API queries
• jq - For JSON parsing (recommended)
• mix - For fetching packages and documentation
• Internet access - For API, web search, and fetching packages/docs

Recommended .gitignore Entries

Add these to your .gitignore to exclude fetched content:

# Fetched Hex documentation and packages
/.hex-docs/
/.hex-packages/

These directories can be large and are easily re-fetched on demand.

Integration

This skill is bundled with the core@elixir plugin and doesn't require separate installation.

See SKILL.md for the complete skill prompt and instructions.