Hex Docs Search

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