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

name, description, allowed-tools

name	description	allowed-tools
hex-docs-search	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.	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