hex-docs-search

name	hex-docs-search
description	Research Hex packages (Sobelow, Phoenix, Ecto, Credo, Ash, etc). Use when investigating packages, understanding integration patterns, or finding module/function docs and usage examples. Automatically fetches missing documentation and source code locally.
allowed-tools	Read, Grep, Glob, Bash, WebSearch, AskUserQuestion

Hex Documentation Search

Comprehensive search for Elixir and Erlang package documentation, following a cascading strategy to find the most relevant and context-aware information.

When to use this skill

Use this skill when you need to:

• Look up documentation for a Hex package or dependency
• Find function signatures, module documentation, or type specs
• See usage examples of a library or module
• Understand how a dependency is used in the current project
• Search for Elixir/Erlang standard library documentation

Search strategy

This skill implements a cascading search that prioritizes local and contextual information:

1. Local dependencies - Search installed packages in deps/ directory (both source code AND generated docs)
2. Fetched cache - Check previously fetched documentation and source code in .hex-docs/ and .hex-packages/
3. Progressive fetch - Automatically fetch missing documentation or source code locally when needed
4. Codebase usage - Find how packages are used in the current project
5. HexDocs API - Search official documentation on hexdocs.pm (fallback)
6. Web search - Fallback to general web search (last resort)

Instructions

Step 1: Identify the search target

Extract the package name and optionally the module or function name from the user's question.

Examples:

• "How do I use Phoenix.LiveView?" → Package: phoenix_live_view, Module: Phoenix.LiveView
• "Show me Ecto query examples" → Package: ecto, Module: Ecto.Query
• "What does Jason.decode!/1 do?" → Package: jason, Module: Jason, Function: decode!

Step 2: Search local dependencies

Use the Glob and Grep tools to search the deps/ directory for BOTH code and documentation:

1. Find the package directory:

   Use Glob: pattern="deps/<package_name>/**/*.ex"
   

   If no results, the package isn't installed locally. Skip to Step 4.

2. Search for module definition in source code:

   Use Grep: pattern="defmodule <ModuleName>", path="deps/<package_name>/lib"
   

3. Search for function definition in source code (if looking for specific function):

   Use Grep: pattern="def <function_name>", path="deps/<package_name>/lib", output_mode="content", -A=5
   

4. Find documentation in source code (@moduledoc/@doc annotations):

   Use Grep: pattern="@moduledoc|@doc", path="deps/<package_name>/lib", output_mode="content", -A=10
   

5. Check for generated HTML documentation (if available):

   Use Glob: pattern="deps/<package_name>/doc/**/*.html"
   

   If HTML docs exist, search them for relevant content:

   Use Grep: pattern="<ModuleName>|<function_name>", path="deps/<package_name>/doc"
   

6. Read the relevant files using the Read tool to get full context from either source or HTML docs.

Step 3: Check fetched cache and fetch if needed

If the package wasn't found in deps/, check for previously fetched documentation or source code, or fetch it now.

3.1: Check fetched documentation cache

Use the Glob tool to check if documentation was previously fetched:

Use Glob: pattern=".hex-docs/docs/hexpm/<package_name>/*/*.html"

If found, search the fetched documentation using the same patterns as Step 2 (sections 5 and 6).

3.2: Check fetched source code cache

Use the Glob tool to check if source code was previously fetched:

Use Glob: pattern=".hex-packages/<package_name>-*/**/*.ex"

If found, search the fetched source using the same patterns as Step 2 (sections 2-4).

3.3: Determine version to fetch

If no cached docs or source found, determine which version to fetch:

1. Check mix.lock for locked version:

   Use Bash: grep '"<package_name>"' mix.lock | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'
   

2. Check mix.exs for version constraint:

   Use Bash: grep -E '\{:<package_name>' mix.exs | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'
   

3. Get latest version from hex.pm:

   Use Bash: curl -s "https://hex.pm/api/packages/<package_name>" | jq -r '.releases[0].version'
   

4. If version ambiguous, use AskUserQuestion to prompt:

   Question: "Package '<package_name>' not found locally. Which version would you like to fetch?"
   Options:
   - "Latest (X.Y.Z)" - Fetch most recent release
   - "Project version (X.Y.Z)" - Use version from mix.exs/mix.lock (if available)
   - "Specific version" - User provides custom version in "Other" field
   - "Skip fetching" - Continue to HexDocs API search without fetching
   

3.4: Progressive fetch (documentation first)

Once version is determined, fetch documentation to project-local cache:

# Use custom HEX_HOME to store in project directory
HEX_HOME=.hex-docs mix hex.docs fetch <package_name> <version>

Storage location: .hex-docs/docs/hexpm/<package_name>/<version>/

If successful:

• Search the fetched HTML documentation using patterns from Step 2 (sections 5-6)
• Read relevant files with the Read tool

If documentation fetch fails (package has no docs) or docs lack sufficient detail:

• Proceed to Step 3.5 to fetch source code

3.5: Fetch source code if needed

If documentation is insufficient or unavailable, fetch package source code:

# Fetch and unpack to project-local directory
mix hex.package fetch <package_name> <version> --unpack --output .hex-packages/<package_name>-<version>

Storage location: .hex-packages/<package_name>-<version>/

If successful:

• Search the source code using patterns from Step 2 (sections 2-4)
• Read source files with the Read tool
• Examine @moduledoc and @doc annotations

If source fetch fails:

• Continue to Step 5 (HexDocs API search) as fallback

3.6: Git ignore recommendation

Inform the user that fetched content should be git-ignored. Suggest adding to .gitignore:

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

This only needs to be mentioned once per session, and only if fetching actually occurred.

Step 4: Search codebase usage

Use the Grep tool to find usage patterns in the current project:

1. Find imports and aliases:

   Use Grep: pattern="alias <ModuleName>|import <ModuleName>", path="lib", output_mode="content", -n=true
   

2. Find function calls:

   Use Grep: pattern="<ModuleName>\.", path="lib", output_mode="content", -A=3
   

3. Search test files for examples:

   Use Grep: pattern="<ModuleName>", path="test", output_mode="content", -A=5
   

This provides real-world usage examples from the current project, which is often the most helpful context.

Step 5: Search HexDocs Search API

If local search doesn't provide sufficient information, use the Bash tool to search the HexDocs search API.

Full-text search across documentation:

# Search across all packages
curl -s "https://search.hexdocs.pm/?q=<query>&query_by=doc,title" | jq -r '.found, .hits[0:5][] | .document | "\(.package) - \(.title)\n\(.doc)\n---"'

# Search within a specific package (get version first)
VERSION=$(curl -s "https://hex.pm/api/packages/<package_name>" | jq -r '.releases[0].version')
curl -s "https://search.hexdocs.pm/?q=<query>&query_by=doc,title&filter_by=package:=[<package>-$VERSION]" | jq -r '.hits[] | .document | "\(.title)\n\(.doc)\nURL: https://hexdocs.pm\(.url)\n---"'

Examples:

# Search for "mount" in phoenix_live_view
VERSION=$(curl -s "https://hex.pm/api/packages/phoenix_live_view" | jq -r '.releases[0].version')
curl -s "https://search.hexdocs.pm/?q=mount&query_by=doc,title&filter_by=package:=[phoenix_live_view-$VERSION]" | jq -r '.hits[0:3][] | .document | "\(.title)\n\(.doc)\n---"'

# General search for Ecto.Query
curl -s "https://search.hexdocs.pm/?q=Ecto.Query&query_by=doc,title" | jq -r '.hits[0:5][] | .document | "\(.package) - \(.title)\n\(.doc)\n"'

API Response structure:

• found: Total number of results
• hits[]: Array of results with:
  • document.package: Package name
  • document.ref: Version
  • document.title: Function/module name
  • document.doc: Documentation text
  • document.url: Path to docs (append to https://hexdocs.pm)

Requirements: curl and jq (available on Linux/Mac, use Git Bash or WSL on Windows)

Step 6: Web search fallback

If the above steps don't provide sufficient information, use the WebSearch tool:

First try searching hexdocs.pm specifically:

Use WebSearch: query="site:hexdocs.pm <package_name> <module_or_function>"

If that doesn't help, do a general search:

Use WebSearch: query="elixir <package_name> <module_or_function> documentation examples"

Output format

When presenting results, organize them as follows:

If found locally:

Found <package_name> in local dependencies:

**Location**: deps/<package_name>
**Version**: <version from mix.lock>

**Documentation**:
<relevant documentation or code snippets>

**Usage in this project**:
<usage examples from codebase>

If found on HexDocs:

Found <package_name> on HexDocs:

**Package**: <package_name>
**Latest version**: <version>
**Documentation**: https://hexdocs.pm/<package_name>/<version>/<Module>.html

<summary of key information>

If using web search:

Searching web for <package_name> documentation:

<summary of web search results>

Examples

Example 1: Finding Phoenix.LiveView documentation

User asks: "How do I use Phoenix.LiveView mount/3?"

Search process:

1. Check deps/phoenix_live_view/ exists
2. Search for def mount in deps/phoenix_live_view/lib/ (source code)
3. Read the @doc annotation for mount/3 from source
4. Check for HTML docs in deps/phoenix_live_view/doc/ and read if available
5. Search project for mount implementations in lib/*/live/*.ex (usage examples)
6. Show documentation and examples from both deps and codebase

Example 2: Looking up Ecto.Query

User asks: "Show me Ecto.Query examples"

Search process:

1. Check deps/ecto/ for source code
2. Search project for import Ecto.Query
3. Find query examples in lib/*/queries/*.ex or lib/*_context.ex
4. If needed, search HexDocs API:

   curl -s "https://search.hexdocs.pm/?q=Ecto.Query&query_by=doc,title" | jq '.hits[0:3]'
   

5. Show local examples first, then external docs

Example 3: Unknown package with progressive fetch

User asks: "How do I use the Timex library?"

Search process:

1. Check deps/timex/ (not found)
2. Check .hex-docs/docs/hexpm/timex/ (not found)
3. Check .hex-packages/timex-*/ (not found)
4. Check mix.exs/mix.lock (not in project dependencies)
5. Get latest version from hex.pm:

   curl -s "https://hex.pm/api/packages/timex" | jq -r '.releases[0].version'
   # Returns: 3.7.11
   

6. Prompt user: "Package 'timex' not found locally. Fetch latest (3.7.11)?"
7. User confirms: "Latest"
8. Fetch documentation:

   HEX_HOME=.hex-docs mix hex.docs fetch timex 3.7.11
   # Stores in: .hex-docs/docs/hexpm/timex/3.7.11/
   

9. Search fetched HTML documentation
10. If docs sufficient, present findings
11. If docs lack detail, offer to fetch source:

    mix hex.package fetch timex 3.7.11 --unpack --output .hex-packages/timex-3.7.11
    

12. Search source code for implementation details
13. Suggest adding to .gitignore if not already present
14. Offer to add it to mix.exs if user wants to use it

Future queries: Documentation and source cached locally for instant offline access

Example 4: Cached documentation (offline-capable)

User asks: "Show me Phoenix.LiveView.mount/3 again"

Search process:

1. Check deps/phoenix_live_view/ (not found)
2. Check .hex-docs/docs/hexpm/phoenix_live_view/ (found version 0.20.0!)
3. No fetch needed - use cached documentation
4. Search cached HTML: .hex-docs/docs/hexpm/phoenix_live_view/0.20.0/Phoenix.LiveView.html
5. Present documentation instantly

Result: Fast, offline search without network requests. Works even when disconnected.

Example 5: Progressive fetch (docs → source)

User asks: "Show me the implementation of Jason.decode!/2"

Search process:

1. Check deps/jason/ (not found)
2. Check .hex-docs/docs/hexpm/jason/ (not found)
3. Check project version in mix.exs: {:jason, "~> 1.4"}
4. Resolve to latest 1.4.x from hex.pm: 1.4.4
5. Fetch docs:

   HEX_HOME=.hex-docs mix hex.docs fetch jason 1.4.4
   

6. Search docs: Find signature but not implementation details
7. Offer: "Documentation shows the signature. Fetch source code for implementation?"
8. User confirms
9. Fetch source:

   mix hex.package fetch jason 1.4.4 --unpack --output .hex-packages/jason-1.4.4
   

10. Search source: .hex-packages/jason-1.4.4/lib/jason.ex
11. Present implementation with line numbers

Result: Both docs and source cached for comprehensive future queries

Tool usage summary

Use Claude's built-in tools in this order:

1. Glob - Find package files in deps/, .hex-docs/, and .hex-packages/
2. Grep - Search for modules, functions, and documentation in deps/, fetched cache, and project code
3. Read - Read full files for detailed documentation
4. Bash - Fetch packages/docs with mix hex commands; Query HexDocs Search API with curl + jq
5. AskUserQuestion - Prompt for version when ambiguous
6. WebSearch - Fallback search for hexdocs.pm or general web

Requirements: curl and jq (Linux/Mac native, use Git Bash or WSL on Windows)

Best practices

1. Start local: Always check local dependencies first - they match the version used in the project
2. Check cache before fetch: Look for previously fetched docs/source in .hex-docs/ and .hex-packages/ before fetching
3. Progressive fetch: Try documentation first (lighter, faster), then source if needed
4. Prompt for clarity: Always prompt for version when ambiguous - don't assume latest is desired
5. Show usage: Real code examples from the current project are more valuable than generic documentation
6. Version awareness: Note which version is installed locally vs latest on hex.pm vs fetched
7. Progressive disclosure: Start with a summary, offer to dive deeper if needed
8. Link to source: Provide file paths (with line numbers) so users can explore further
9. Git ignore reminder: Mention .gitignore addition once per session when fetching occurs
10. Offline capability: Once fetched, documentation and source available without network access

Troubleshooting

Package not found in deps/

• Check .hex-docs/ and .hex-packages/ for previously fetched content
• If not cached, determine version and offer to fetch
• Check if it's in mix.exs dependencies (for version resolution)
• Suggest running mix deps.get if it should be a project dependency
• Search hex.pm to verify the package exists

Fetch failures

Documentation fetch fails:

• Package may not have published docs (some packages only have source)
• Offer to fetch source code instead
• Fall back to HexDocs API search

Source fetch fails:

• Verify package name spelling
• Check network connectivity
• Fall back to HexDocs API search

Cache location issues

Fetched content not found on repeat queries:

• Verify .hex-docs/ and .hex-packages/ directories exist
• Check that fetch commands completed successfully
• May need to re-fetch if directories were deleted

No documentation in deps/

• Some packages don't include @doc annotations
• Fall back to hexdocs.pm search
• Read the source code directly and explain it

HexDocs API rate limiting

• If the API is rate limited, fall back to web search
• Cache results when possible
• Use web search with site:hexdocs.pm filter