Essential Elixir development support with hooks and automation
- GitHub stars
- 176
Install
/plugin install core@elixirRun it inside Claude Code after adding the marketplace with /plugin marketplace add bradleygolden/claude-marketplace-elixir.
Contents
Discovered from sourceSkills 2
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:
- Local dependencies - Search installed packages in
deps/directory (both source code AND generated docs) - Fetched cache - Check previously fetched documentation and source code in
.hex-docs/and.hex-packages/ - Progressive fetch - Automatically fetch missing documentation or source code locally when needed
- Codebase usage - Find how packages are used in the current project
- HexDocs API - Search official documentation on hexdocs.pm (fallback)
- 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:
-
Find the package directory:
Use Glob: pattern="deps/<package_name>/**/*.ex"If no results, the package isn't installed locally. Skip to Step 4.
-
Search for module definition in source code:
Use Grep: pattern="defmodule <ModuleName>", path="deps/<package_name>/lib" -
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 -
Find documentation in source code (@moduledoc/@doc annotations):
Use Grep: pattern="@moduledoc|@doc", path="deps/<package_name>/lib", output_mode="content", -A=10 -
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" -
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:
-
Check mix.lock for locked version:
Use Bash: grep '"<package_name>"' mix.lock | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' -
Check mix.exs for version constraint:
Use Bash: grep -E '\{:<package_name>' mix.exs | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' -
Get latest version from hex.pm:
Use Bash: curl -s "https://hex.pm/api/packages/<package_name>" | jq -r '.releases[0].version' -
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:
-
Find imports and aliases:
Use Grep: pattern="alias <ModuleName>|import <ModuleName>", path="lib", output_mode="content", -n=true -
Find function calls:
Use Grep: pattern="<ModuleName>\.", path="lib", output_mode="content", -A=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 resultshits[]: Array of results with:document.package: Package namedocument.ref: Versiondocument.title: Function/module namedocument.doc: Documentation textdocument.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:
- Check
deps/phoenix_live_view/exists - Search for
def mountindeps/phoenix_live_view/lib/(source code) - Read the
@docannotation formount/3from source - Check for HTML docs in
deps/phoenix_live_view/doc/and read if available - Search project for
mountimplementations inlib/*/live/*.ex(usage examples) - Show documentation and examples from both deps and codebase
Example 2: Looking up Ecto.Query
User asks: "Show me Ecto.Query examples"
Search process:
- Check
deps/ecto/for source code - Search project for
import Ecto.Query - Find query examples in
lib/*/queries/*.exorlib/*_context.ex - If needed, search HexDocs API:
curl -s "https://search.hexdocs.pm/?q=Ecto.Query&query_by=doc,title" | jq '.hits[0:3]' - 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:
- Check
deps/timex/(not found) - Check
.hex-docs/docs/hexpm/timex/(not found) - Check
.hex-packages/timex-*/(not found) - Check mix.exs/mix.lock (not in project dependencies)
- Get latest version from hex.pm:
curl -s "https://hex.pm/api/packages/timex" | jq -r '.releases[0].version' # Returns: 3.7.11 - Prompt user: "Package 'timex' not found locally. Fetch latest (3.7.11)?"
- User confirms: "Latest"
- Fetch documentation:
HEX_HOME=.hex-docs mix hex.docs fetch timex 3.7.11 # Stores in: .hex-docs/docs/hexpm/timex/3.7.11/ - Search fetched HTML documentation
- If docs sufficient, present findings
- If docs lack detail, offer to fetch source:
mix hex.package fetch timex 3.7.11 --unpack --output .hex-packages/timex-3.7.11 - Search source code for implementation details
- Suggest adding to .gitignore if not already present
- 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:
- Check
deps/phoenix_live_view/(not found) - Check
.hex-docs/docs/hexpm/phoenix_live_view/(found version 0.20.0!) - No fetch needed - use cached documentation
- Search cached HTML:
.hex-docs/docs/hexpm/phoenix_live_view/0.20.0/Phoenix.LiveView.html - 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:
- Check
deps/jason/(not found) - Check
.hex-docs/docs/hexpm/jason/(not found) - Check project version in mix.exs:
{:jason, "~> 1.4"} - Resolve to latest 1.4.x from hex.pm: 1.4.4
- Fetch docs:
HEX_HOME=.hex-docs mix hex.docs fetch jason 1.4.4 - Search docs: Find signature but not implementation details
- Offer: "Documentation shows the signature. Fetch source code for implementation?"
- User confirms
- Fetch source:
mix hex.package fetch jason 1.4.4 --unpack --output .hex-packages/jason-1.4.4 - Search source:
.hex-packages/jason-1.4.4/lib/jason.ex - 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:
- Glob - Find package files in deps/, .hex-docs/, and .hex-packages/
- Grep - Search for modules, functions, and documentation in deps/, fetched cache, and project code
- Read - Read full files for detailed documentation
- Bash - Fetch packages/docs with mix hex commands; Query HexDocs Search API with curl + jq
- AskUserQuestion - Prompt for version when ambiguous
- 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
- Start local: Always check local dependencies first - they match the version used in the project
- Check cache before fetch: Look for previously fetched docs/source in
.hex-docs/and.hex-packages/before fetching - Progressive fetch: Try documentation first (lighter, faster), then source if needed
- Prompt for clarity: Always prompt for version when ambiguous - don't assume latest is desired
- Show usage: Real code examples from the current project are more valuable than generic documentation
- Version awareness: Note which version is installed locally vs latest on hex.pm vs fetched
- Progressive disclosure: Start with a summary, offer to dive deeper if needed
- Link to source: Provide file paths (with line numbers) so users can explore further
- Git ignore reminder: Mention .gitignore addition once per session when fetching occurs
- 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.getif 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.pmfilter
Usage Rules Search
Comprehensive search for Elixir and Erlang package usage rules and best practices, following a cascading strategy to find the most relevant coding conventions and patterns.
When to use this skill
Use this skill when you need to:
- Look up coding conventions for a Hex package
- Find best practices and recommended patterns
- See good/bad code examples for proper usage
- Understand common mistakes to avoid
- Learn package-specific idioms and conventions
- Get context-aware recommendations for implementation
Search strategy
This skill implements a cascading search that prioritizes local and contextual information:
- Local dependencies - Search installed packages in
deps/directory for usage-rules.md - Fetched cache - Check previously fetched usage rules in
.usage-rules/ - Progressive fetch - Automatically fetch package and extract usage-rules.md if missing
- Context-aware extraction - Extract relevant sections based on coding context
- Fallback - Note when package doesn't provide usage rules, suggest alternatives
Instructions
Step 1: Identify the package and context
Extract the package name and identify the coding context from the user's question.
Package name examples:
- "Ash best practices" → Package:
ash - "Phoenix LiveView patterns" → Package:
phoenix_live_view - "How to use Ecto properly?" → Package:
ecto
Context keywords:
- Querying: "query", "filter", "search", "find", "list"
- Error handling: "error", "validation", "exception", "handle"
- Actions: "create", "update", "delete", "action", "change"
- Relationships: "relationship", "association", "belongs_to", "has_many"
- Testing: "test", "testing", "mock", "fixture"
- Authorization: "authorization", "permissions", "policy", "access"
- Structure: "structure", "organization", "architecture", "setup"
Step 2: Search local dependencies
Use the Glob and Grep tools to search the deps/ directory for usage rules:
-
Find the package directory with usage-rules.md:
Use Glob: pattern="deps/<package_name>/usage-rules.md"If no results, the package isn't installed locally or doesn't provide usage rules. Skip to Step 3.
-
Check for sub-rules (advanced packages may have specialized rules):
Use Glob: pattern="deps/<package_name>/usage-rules/*.md" -
Search for relevant sections based on context keywords:
Use Grep: pattern="^## (Querying|Error Handling|Actions)", path="deps/<package_name>/usage-rules.md", output_mode="content", -n=trueThis finds section headings with line numbers.
-
Extract relevant sections:
Use Grep: pattern="^## Error Handling", path="deps/<package_name>/usage-rules.md", output_mode="content", -A=50Use
-Aflag to get section content (adjust number based on typical section length). -
Read the complete file if needed for broader context:
Use Read: file_path="deps/<package_name>/usage-rules.md"
Step 3: Check fetched cache and fetch if needed
If the package wasn't found in deps/, check for previously fetched usage rules, or fetch them now.
3.1: Check fetched cache
Use the Glob tool to check if usage rules were previously fetched:
Use Glob: pattern=".usage-rules/<package_name>-*/usage-rules.md"
If found, search the cached rules using the same patterns as Step 2 (sections 3-5).
3.2: Determine version to fetch
If no cached rules found, determine which version to fetch:
-
Check mix.lock for locked version:
Use Bash: grep '"<package_name>"' mix.lock | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' -
Check mix.exs for version constraint:
Use Bash: grep -E '\{:<package_name>' mix.exs | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' -
Get latest version from hex.pm:
Use Bash: curl -s "https://hex.pm/api/packages/<package_name>" | jq -r '.releases[0].version' -
If version ambiguous, use AskUserQuestion to prompt:
Question: "Package '<package_name>' usage rules 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 without usage rules
3.3: Fetch package and extract usage rules
Once version is determined, fetch the package and extract usage-rules.md:
# Create temp directory and fetch package
mkdir -p .usage-rules/.tmp
mix hex.package fetch <package_name> <version> --unpack --output .usage-rules/.tmp/<package_name>-<version>
# Check if usage-rules.md exists
if [ -f ".usage-rules/.tmp/<package_name>-<version>/usage-rules.md" ]; then
# Create version-specific directory
mkdir -p ".usage-rules/<package_name>-<version>"
# Copy main usage rules file
cp ".usage-rules/.tmp/<package_name>-<version>/usage-rules.md" ".usage-rules/<package_name>-<version>/"
# Copy sub-rules if present
if [ -d ".usage-rules/.tmp/<package_name>-<version>/usage-rules/" ]; then
cp -r ".usage-rules/.tmp/<package_name>-<version>/usage-rules/" ".usage-rules/<package_name>-<version>/"
fi
echo "Usage rules cached in .usage-rules/<package_name>-<version>/"
else
echo "Package does not provide usage-rules.md"
fi
# Clean up temp directory
rm -rf ".usage-rules/.tmp/<package_name>-<version>"
Storage location: .usage-rules/<package_name>-<version>/
If successful:
- Search the cached usage rules using patterns from Step 2
- Read relevant files with the Read tool
If package doesn't include usage-rules.md:
- Package may not have adopted usage rules convention
- Proceed to Step 5 (fallback suggestions)
3.4: Git ignore recommendation
Inform the user that fetched usage rules should be git-ignored. Suggest adding to .gitignore:
# Fetched usage rules
/.usage-rules/
This only needs to be mentioned once per session, and only if fetching actually occurred.
Step 4: Extract relevant sections based on context
Usage rules files can be large (1000+ lines). Extract only relevant sections to avoid context overload.
4.1: Find section headings
# Find all h2 section headings with line numbers
Use Grep: pattern="^## ", path=".usage-rules/<package>-<version>/usage-rules.md", output_mode="content", -n=true
This returns a list like:
7:## Understanding Ash
13:## Code Structure & Organization
21:## Code Interfaces
85:## Actions
120:## Querying Data
4.2: Match context to sections
Based on user's context keywords, identify relevant sections:
Context: "querying" → Look for sections containing:
- "Querying", "Query", "Filters", "Search", "Find"
Context: "error handling" → Look for sections containing:
- "Error", "Validation", "Exception", "Handle"
Context: "actions" → Look for sections containing:
- "Actions", "Create", "Update", "Delete", "CRUD"
4.3: Extract matched sections
# Extract specific section with content
Use Grep: pattern="^## Querying Data", path=".usage-rules/<package>-<version>/usage-rules.md", output_mode="content", -A=80
Adjust -A value based on typical section length:
- Small sections (< 50 lines):
-A=50 - Medium sections (50-150 lines):
-A=100 - Large sections (> 150 lines):
-A=150or read specific ranges
4.4: Include code examples
Look for code blocks within sections:
# Find code examples in section
Use Grep: pattern="```elixir|# GOOD|# BAD", path=".usage-rules/<package>-<version>/usage-rules.md", output_mode="content", -A=10
Code examples often include:
- Good patterns: Marked with
# GOOD,# PREFERRED - Bad patterns: Marked with
# BAD,# AVOID,# WRONG - Inline comments: Explanatory comments in code blocks
Step 5: Present usage rules
Format the output based on what was found.
Output format
When presenting results, organize them as follows:
If found in local dependencies:
Found usage rules for <package_name>:
**Location**: deps/<package_name>/usage-rules.md
**Version**: <version from mix.lock>
**Relevant Best Practices** (<section_name>):
<extracted section content with code examples>
---
**Full Rules**: deps/<package_name>/usage-rules.md
**Integration**: For API documentation, use the hex-docs-search skill.
If found in fetched cache:
Found cached usage rules for <package_name>:
**Version**: <version>
**Cache Location**: .usage-rules/<package>-<version>/usage-rules.md
**Relevant Best Practices** (<section_name>):
<extracted section content with code examples>
---
**Full Rules**: .usage-rules/<package>-<version>/usage-rules.md
**Note**: Rules are cached locally for offline access.
**Integration**: For API documentation, use the hex-docs-search skill.
If usage rules not available:
Package '<package_name>' does not provide usage-rules.md.
**Note**: Usage rules are a community-driven convention where packages provide
best practices in markdown format. Not all packages have adopted this yet.
**Alternatives**:
- Use hex-docs-search skill for API documentation and guides
- Check package README or official documentation
- Search for "<package_name> elixir best practices" online
- Look for community guides and blog posts
**Current packages with usage rules**:
- ash, ash_postgres, ash_json_api (Ash Framework ecosystem)
- igniter, spark, reactor (Build tools and engines)
**Help the ecosystem**: Encourage package maintainers to add usage-rules.md!
If user needs comprehensive guidance:
For comprehensive implementation guidance, use both:
1. **usage-rules skill** - Coding conventions and best practices
2. **hex-docs-search skill** - API documentation and function signatures
Combining both provides complete "how to implement correctly" guidance.
Examples
Example 1: Finding Ash querying best practices
User asks: "What are the best practices for querying data in Ash?"
Search process:
- Extract package:
ash - Identify context: "querying"
- Check
deps/ash/usage-rules.md(found) - Search for section:
## Querying Data - Extract section with code examples
- Present best practices
Output:
Found usage rules for ash:
**Location**: deps/ash/usage-rules.md
**Version**: 3.5.20
**Relevant Best Practices** (Querying Data):
## Querying Data
### Common Query Operations
Prefer using code interface functions with the `query` option for filtering, sorting, and limiting:
```elixir
# PREFERRED - Use the query option
posts = MyApp.Blog.list_posts!(
query: [
filter: [status: :published],
sort: [published_at: :desc],
limit: 10
],
load: [author: :profile]
)
# AVOID - Don't build queries manually outside domain
query = MyApp.Blog.Post
|> Ash.Query.filter(status: :published)
|> Ash.Query.sort(published_at: :desc)
posts = Ash.read!(query)
All query-related options go in the query parameter, not as separate arguments.
Full Rules: deps/ash/usage-rules.md
Integration: For Ecto.Query API documentation, use hex-docs-search skill.
### Example 2: Error handling conventions
**User asks**: "How should I handle errors in Phoenix LiveView?"
**Search process**:
1. Extract package: `phoenix_live_view`
2. Identify context: "error handling"
3. Check `deps/phoenix_live_view/usage-rules.md` (not found - LiveView doesn't provide usage rules yet)
4. Check `.usage-rules/phoenix_live_view-*/usage-rules.md` (not found)
5. Attempt fetch (package doesn't include usage-rules.md)
6. Provide fallback suggestions
**Output**:
Package 'phoenix_live_view' does not provide usage-rules.md.
Alternatives:
- Use hex-docs-search skill for Phoenix.LiveView API documentation
- Check Phoenix LiveView guides: https://hexdocs.pm/phoenix_live_view/
- Search for "phoenix liveview error handling best practices"
Note: Usage rules are a community convention. Help the ecosystem by encouraging package maintainers to add usage-rules.md files!
### Example 3: Unknown package with progressive fetch
**User asks**: "What are the best practices for using Spark DSL?"
**Search process**:
1. Extract package: `spark`
2. Identify context: general (no specific context)
3. Check `deps/spark/usage-rules.md` (not found)
4. Check `.usage-rules/spark-*/usage-rules.md` (not found)
5. Check mix.exs: `{:spark, "~> 2.0"}`
6. Get latest 2.x from hex.pm:
```bash
curl -s "https://hex.pm/api/packages/spark" | jq -r '.releases[] | select(.version | startswith("2.")) | .version' | head -1
# Returns: 2.2.24
- Fetch package:
mix hex.package fetch spark 2.2.24 --unpack --output .usage-rules/.tmp/spark-2.2.24 - Extract usage-rules.md (found!)
- Copy to cache:
.usage-rules/spark-2.2.24/usage-rules.md - Clean up temp
- Read and present usage rules
Output:
Found cached usage rules for spark:
**Version**: 2.2.24
**Cache Location**: .usage-rules/spark-2.2.24/usage-rules.md
**Relevant Best Practices** (Understanding Spark):
## Understanding Spark
Spark is a foundation for declarative DSLs in Elixir. It powers frameworks like Ash
by providing the infrastructure for building expressive, compile-time-validated DSLs.
### Key Concepts
- **Extensions**: Modules that add DSL sections to Spark DSLs
- **Sections**: Top-level DSL constructs (like `actions do ... end`)
- **Entities**: Individual items within sections (like `read :list`)
- **Options**: Configuration for entities
<...more content...>
---
**Full Rules**: .usage-rules/spark-2.2.24/usage-rules.md
**Note**: Rules are now cached locally for offline access.
**Recommendation**: Add `.usage-rules/` to your .gitignore.
Example 4: Cached rules (offline access)
User asks: "Show me Ash relationship best practices again"
Search process:
- Extract package:
ash - Identify context: "relationship"
- Check
deps/ash/usage-rules.md(not found - not in project) - Check
.usage-rules/ash-*/usage-rules.md(found version 3.5.20!) - No fetch needed - use cached rules
- Search for "## Relationships" section
- Extract and present
Result: Fast, offline search without network requests. Works even when disconnected.
Example 5: Context-aware extraction
User asks: "Common mistakes with Ash actions?"
Search process:
- Extract package:
ash - Identify context: "actions" + "mistakes"
- Find usage rules (local or cached)
- Search for "## Actions" section
- Also search for keywords: "mistake", "avoid", "wrong", "bad"
- Extract relevant parts from multiple sections
- Present consolidated best practices
Output:
Found usage rules for ash:
**Relevant Best Practices** (Actions - Common Mistakes):
## Actions
**AVOID** - Don't create generic CRUD actions:
```elixir
# BAD - Generic naming
create :create
update :update
PREFER - Create domain-specific actions:
# GOOD - Specific business operations
create :register_user
update :activate_account
update :suspend_for_violation
AVOID - Don't put business logic outside actions:
# BAD - Logic in controller
def create_post(conn, params) do
{:ok, post} = Blog.create_post(params)
# Business logic here
send_notifications(post)
update_stats()
end
PREFER - Put business logic in action changes:
# GOOD - Logic in action
create :publish_post do
change after_action(fn _changeset, post ->
send_notifications(post)
update_stats()
{:ok, post}
end)
end
Full Rules: deps/ash/usage-rules.md
Tool usage summary
Use Claude's built-in tools in this order:
- Glob - Find usage-rules.md files in deps/, .usage-rules/, and check for sub-rules
- Grep - Search for section headings, context keywords, and code examples
- Read - Read complete usage rules files when broader context needed
- Bash - Fetch packages with mix hex.package, version resolution, extract and cache rules
- AskUserQuestion - Prompt for version when ambiguous
Requirements: curl and jq (Linux/Mac native, use Git Bash or WSL on Windows)
Best practices
- Start local: Always check local dependencies first - they match the version used in the project
- Check cache before fetch: Look for previously fetched rules in
.usage-rules/before fetching - Context-aware extraction: Don't present entire file - extract relevant sections based on keywords
- Show code examples: Always include good/bad pattern examples when available
- Highlight patterns: Point out
# GOODvs# BADcomparisons explicitly - Link to source: Provide file path so users can explore complete rules
- Note integration: Mention hex-docs-search for complementary API documentation
- Git ignore reminder: Mention .gitignore addition once per session when fetching occurs
- Offline capability: Once fetched, usage rules available without network access
- Version awareness: Note which version is installed locally vs fetched from cache
Troubleshooting
Package not found in deps/
- Check
.usage-rules/for previously fetched rules - If not cached, determine version and offer to fetch
- Check if package is in mix.exs dependencies (for version resolution)
- Verify package name spelling (convert
Phoenix.LiveView→phoenix_live_view)
Package doesn't provide usage-rules.md
- This is expected - usage rules are a convention, not all packages have them
- Fallback to hex-docs-search for API documentation
- Suggest checking package README or guides
- Encourage package maintainers to add usage rules
Fetch failures
Package fetch fails:
- Verify package name spelling
- Check network connectivity
- Verify package exists on hex.pm
- Try web search as fallback
Extraction fails:
- Package was fetched but doesn't include usage-rules.md
- Clean up temp directory
- Note that package doesn't provide rules
Cache location issues
Fetched rules not found on repeat queries:
- Verify
.usage-rules/directory exists - Check that fetch command completed successfully
- May need to re-fetch if directories were deleted
- Ensure temp cleanup didn't remove permanent cache
Section extraction challenges
Section too large:
- Increase
-Avalue in Grep to get more content - Or read complete file and extract programmatically
- Consider showing summary + offering full section
Multiple relevant sections:
- Extract multiple sections
- Present them in logical order
- Clearly label each section
No section matches context:
- Show "## Understanding [Package]" section as default
- List available sections for user to choose from
- Read complete file if user wants comprehensive overview
Version mismatches
Different version in deps/ vs cache:
- Prefer deps/ version (matches project)
- Note version difference if using cache
- Offer to fetch version matching project dependencies
Version specified doesn't exist:
- List available versions from hex.pm
- Prompt user to select valid version
- Fall back to latest if user unsure
Hooks 2
Sponsors
Details
- Marketplace
- bradleygolden/claude-marketplace-elixir
- Source
- plugins/core
- Category
- Community
- License
- MIT
- Keywords
- elixir, erlang, beam, otp, functional
