7.9 KiB
Usage Rules Search Skill
A comprehensive skill for searching Elixir and Erlang package usage rules and best practices using a cascading strategy.
Overview
This skill helps Claude search for package usage rules intelligently by:
- Local dependencies - Searches installed packages in
deps/directory - Fetched cache - Checks previously fetched usage rules in
.usage-rules/ - Progressive fetch - Automatically fetches missing usage rules when needed
- Context-aware extraction - Extracts relevant sections based on coding context
- Fallback guidance - Provides alternatives when rules unavailable
Usage
This skill is automatically available when the core@elixir plugin is installed. Claude will use it when appropriate, for example:
User: "What are Ash best practices for querying?"
User: "Show me error handling patterns in Phoenix"
User: "How should I structure Ecto schemas?"
User: "What are common mistakes with LiveView?"
User: "Best practices for Ash relationships"
How it Works
1. Local Dependencies Search (deps/)
Searches installed packages for usage-rules.md files:
- Finds usage rules matching your project's version
- Searches for relevant sections based on context
- Extracts code examples with good/bad patterns
Advantage: Matches the exact version used in the project
2. Fetched Cache Search (.usage-rules/)
Checks for previously fetched usage rules:
- Searches
.usage-rules/<package>-<version>/usage-rules.md - Includes sub-rules if package provides them
- Uses same search patterns as deps/
Advantage: Fast, offline-capable access to packages not in project dependencies
3. Progressive Fetch
When usage rules 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)
- Package fetch: Downloads package with
mix hex.package fetch - Extraction: Copies usage-rules.md to
.usage-rules/<package>-<version>/ - Cached for future: All fetched rules reusable in subsequent queries
Advantage: Builds a local knowledge base of usage rules over time
4. Context-Aware Extraction
Extracts relevant sections based on what you're working on:
- Querying → "## Querying Data" section
- Error handling → "## Error Handling" section
- Actions → "## Actions" section
- Relationships → "## Relationships" section
- Testing → "## Testing" section
Advantage: Focused guidance without overwhelming context
5. Fallback Guidance
When package doesn't provide usage rules:
- Notes that package hasn't adopted convention
- Suggests using hex-docs-search for API documentation
- Recommends checking package README or guides
- Lists packages that currently have usage rules
Advantage: Graceful handling of unavailable rules
Examples
Example 1: Looking up Ash querying best practices
User: "What are Ash best practices for querying?"
Claude will:
1. Find deps/ash/usage-rules.md or .usage-rules/ash-*/usage-rules.md
2. Extract "## Querying Data" section
3. Show code examples with GOOD/BAD patterns
4. Provide file path for full rules
Example 2: Unknown package with progressive fetch
User: "What are Spark DSL best practices?"
Claude will:
1. Check deps/spark/usage-rules.md (not found)
2. Check .usage-rules/spark-*/usage-rules.md (not found)
3. Detect version from mix.exs or query hex.pm
4. Prompt: "Fetch Spark 2.2.24 usage rules?"
5. User confirms: "Latest"
6. Fetch: mix hex.package fetch spark 2.2.24 --unpack
7. Extract: .usage-rules/spark-2.2.24/usage-rules.md
8. Present usage rules with relevant sections
9. Suggest adding to .gitignore
Future queries: Instant access to cached rules
Example 3: Cached rules (offline access)
User: "Show me Ash relationship best practices again"
Claude will:
1. Check deps/ash/usage-rules.md (not found)
2. Check .usage-rules/ash-*/usage-rules.md (found version 3.5.20!)
3. **No fetch needed** - use cached rules
4. Extract "## Relationships" section
5. Present instantly
Result: Fast, offline search without network requests
Example 4: Package without usage rules
User: "Phoenix LiveView best practices?"
Claude will:
1. Check for usage rules (not found)
2. Note that LiveView doesn't provide usage-rules.md yet
3. Suggest alternatives:
- Use hex-docs-search for API documentation
- Check Phoenix LiveView guides
- Search web for community practices
Example 5: Context-aware extraction
User: "Common mistakes with Ash actions?"
Claude will:
1. Find Ash usage rules
2. Identify context: "actions" + "mistakes"
3. Extract "## Actions" section
4. Search for keywords: "mistake", "avoid", "bad", "wrong"
5. Present consolidated best practices with patterns to avoid
Requirements
curl- For hex.pm API queriesjq- For JSON parsingmix- For fetching packages
These are standard on Linux/Mac, use Git Bash or WSL on Windows.
Recommended .gitignore Entries
Add these to your .gitignore to exclude fetched usage rules:
# Fetched usage rules
/.usage-rules/
These directories can be large and are easily re-fetched on demand.
Integration with hex-docs-search
This skill focuses on coding conventions and best practices. For API documentation (function signatures, parameters, return values), use the hex-docs-search skill.
Comprehensive guidance: Agents can invoke both skills to provide complete "how to use it correctly" guidance:
- usage-rules: Conventions, patterns, good/bad examples
- hex-docs-search: API documentation, function signatures
Example:
User: "Help me implement Ash queries properly"
Agent combines both:
1. usage-rules: Get Ash querying conventions (use code interfaces, avoid manual queries)
2. hex-docs-search: Get Ecto.Query API documentation (filter operators, query functions)
3. Synthesize: "Here's how to do it (conventions) + what's available (API)"
Current Usage Rules Availability
Packages with usage rules (as of 2025-10-31):
- Ash ecosystem: ash, ash_postgres, ash_json_api
- Build tools: igniter, spark, reactor
Note: Usage rules are a community-driven convention. Not all packages have adopted this yet, but adoption is growing.
Help the ecosystem: Encourage package maintainers to add usage-rules.md files! These files help both humans and AI understand best practices.
What are Usage Rules?
Usage rules are LLM-optimized markdown files (usage-rules.md) that packages provide to guide proper usage:
Characteristics:
- Located at package root:
<package>/usage-rules.md - Dense, token-efficient format
- Code-first with good/bad examples
- Organized by topic (querying, error handling, testing, etc.)
- Includes inline comments and quick references
Example structure:
# Rules for working with Ash
## Understanding Ash
[High-level overview]
## Code Structure & Organization
[Conventions for organizing code]
## Querying Data
```elixir
# GOOD - Use code interface
MyApp.Blog.list_posts!(query: [filter: [status: :published]])
# BAD - Don't bypass domain
Ash.Query.filter(MyApp.Blog.Post, status: :published) |> Ash.read!()
## How to Create Usage Rules
If you're a package maintainer:
1. Create `usage-rules.md` in your package root
2. Start with "# Rules for working with [Package]"
3. Add "## Understanding [Package]" section (overview)
4. Organize by common tasks and features
5. Use code examples with `# GOOD` and `# BAD` patterns
6. Keep it dense and token-efficient
7. Include in your hex package `files` list
See [Ash's usage-rules.md](https://github.com/ash-project/ash/blob/main/usage-rules.md) for a comprehensive example.
## 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.