Initial commit

skills/hex-docs-search/README.md

@@ -0,0 +1,155 @@
+# 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:
+
+```gitignore
+# 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](SKILL.md) for the complete skill prompt and instructions.