home / skills / michalvavra / agents / search-hexdocs

search-hexdocs skill

safe

/skills/search-hexdocs

This skill helps you search Hexdocs documentation for Elixir and Erlang packages, returning results with optional package filters and JSON output.

npx playbooks add skill michalvavra/agents --skill search-hexdocs

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

928 B

---
name: search-hexdocs
description: Search Hex package documentation for Elixir/Erlang.
compatibility: Requires Node.js 18+. Run `npm install` in {baseDir}/scripts first.
---

# Search hexdocs

Search [hexdocs.pm](https://hexdocs.pm) documentation.

## Usage

```bash
{baseDir}/scripts/hexdocs.js <QUERY> [OPTIONS]
```

## Examples

```bash
# Search all packages
{baseDir}/scripts/hexdocs.js "GenServer callbacks"

# Filter by package
{baseDir}/scripts/hexdocs.js "Ecto.Query" --packages ecto

# Multiple packages
{baseDir}/scripts/hexdocs.js "LiveView hooks" --packages phoenix_live_view,phoenix

# Limit results
{baseDir}/scripts/hexdocs.js "plug conn" --limit 5

# JSON output
{baseDir}/scripts/hexdocs.js "json encode" --packages jason --json
```

## Output Format

```
Results: 42 (showing 10)

<result index="0" package="phoenix" ref="Phoenix.Controller.html#json/2" title="json/2">
Sends JSON response...
</result>
```

Overview

This skill lets an AI search HexDocs package documentation for Elixir and Erlang projects. It runs a command-line query against hexdocs.pm and returns matching documentation references and snippets. Results can be filtered by package, limited in number, and emitted as JSON for programmatic consumption.

How this skill works

You provide a text query and optional flags; the script crawls indexed HexDocs pages and scores matches by relevance. It supports package filters, result limits, and a JSON output mode. The output lists results with package, reference, title, and a short excerpt so you can quickly locate the exact API or guide.

When to use it

When you need precise API references or examples from HexDocs for Elixir/Erlang libraries.
When troubleshooting unfamiliar callbacks, functions, or module behaviors across packages.
During code reviews to verify correct usage of library functions or configuration options.
When preparing documentation, blog posts, or learning materials and you need authoritative source links.
When building tools or scripts that need to fetch documentation snippets programmatically.

Best practices

Start with concise queries (module or function names) and broaden only if needed to reduce noise.
Use --packages to restrict search to known dependencies to improve relevance and speed.
Set --limit to a small number for quick checks, or higher for deeper research sessions.
Enable --json when integrating results into tooling, bots, or automated reports.
Inspect the returned reference anchor (ref) to jump directly to the exact API section.

Example use cases

Find the exact GenServer callback spec and example to implement handle_call correctly.
Search for Ecto.Query functions and options across the ecto package documentation.
Locate LiveView hook documentation within phoenix_live_view to implement client-side hooks.
Quickly retrieve JSON encoding details from the jason package for serialization decisions.
Integrate into a CI job that verifies project code references still exist in upstream docs.

FAQ

Can I restrict search to multiple packages?

Yes. Pass a comma-separated list with --packages to limit results to specific packages.

How do I get machine-readable results?

Use the --json flag to output results as JSON, making it easy to parse and consume.