Usage Rules Search
Find package-specific best practices and coding conventions from usage-rules.md files.
What Are Usage Rules?
A community convention where packages include a usage-rules.md file with:
- Coding conventions and patterns
- Good/bad code examples (marked
# GOOD, # BAD, # AVOID)
- Common mistakes to avoid
- Domain-specific idioms
Search Locations (in order)
- Project deps:
deps/<package>/usage-rules.md
- Fetched cache:
.usage-rules/<package>-<version>/usage-rules.md
- Fetch if needed: Extract from package (see below)
Packages With Usage Rules
Primarily the Ash ecosystem:
ash, ash_postgres, ash_phoenix, ash_json_api, ash_graphqlspark, igniter, reactor
Most packages (Phoenix, Ecto, etc.) do not have usage-rules.md yet. For those, suggest hex-docs-search skill or official guides.
Fetching Usage Rules
# Fetch package and extract usage-rules.md
mix hex.package fetch <package> <version> --unpack --output .usage-rules/.tmp/<package>-<version>
# If usage-rules.md exists, copy to cache
if [ -f ".usage-rules/.tmp/<package>-<version>/usage-rules.md" ]; then
mkdir -p ".usage-rules/<package>-<version>"
cp ".usage-rules/.tmp/<package>-<version>/usage-rules.md" ".usage-rules/<package>-<version>/"
fi
# Clean up
rm -rf ".usage-rules/.tmp/<package>-<version>"
Mention adding .usage-rules/ to .gitignore once per session when fetching occurs.
Context-Aware Extraction
Usage rules files can be large. Extract relevant sections based on user's question:
| User Context |
Look for Sections |
| querying, filters |
"Querying", "Filters", "Read Actions" |
| actions, create/update |
"Actions", "Changes", "Validations" |
| relationships |
"Relationships", "Aggregates" |
| errors, validation |
"Error Handling", "Validations" |
| authorization |
"Policies", "Authorization" |
| testing |
"Testing" |
Find section headings with line numbers, then extract the relevant section content.
Key Behaviors
- Extract relevant sections, don't dump entire file
- Highlight
# GOOD vs # BAD patterns explicitly
- Note when package doesn't provide usage rules
- Suggest
hex-docs-search for API documentation (complementary)
- Version awareness: prefer deps/ version over cached
1---2name: usage-rules-23description: Search for package-specific usage rules and best practices from Elixir packages. Use when you need coding conventions, patterns, common mistakes, or good/bad examples for packages like Ash, Phoenix, Ecto, etc.4---56# Usage Rules Search78Find package-specific best practices and coding conventions from `usage-rules.md` files.910## What Are Usage Rules?1112A community convention where packages include a `usage-rules.md` file with:13- Coding conventions and patterns14- Good/bad code examples (marked `# GOOD`, `# BAD`, `# AVOID`)15- Common mistakes to avoid16- Domain-specific idioms1718## Search Locations (in order)19201. **Project deps**: `deps/<package>/usage-rules.md`212. **Fetched cache**: `.usage-rules/<package>-<version>/usage-rules.md`223. **Fetch if needed**: Extract from package (see below)2324## Packages With Usage Rules2526Primarily the Ash ecosystem:27- `ash`, `ash_postgres`, `ash_phoenix`, `ash_json_api`, `ash_graphql`28- `spark`, `igniter`, `reactor`2930Most packages (Phoenix, Ecto, etc.) do not have usage-rules.md yet. For those, suggest `hex-docs-search` skill or official guides.3132## Fetching Usage Rules3334```bash35# Fetch package and extract usage-rules.md36mix hex.package fetch <package> <version> --unpack --output .usage-rules/.tmp/<package>-<version>3738# If usage-rules.md exists, copy to cache39if [ -f ".usage-rules/.tmp/<package>-<version>/usage-rules.md" ]; then40 mkdir -p ".usage-rules/<package>-<version>"41 cp ".usage-rules/.tmp/<package>-<version>/usage-rules.md" ".usage-rules/<package>-<version>/"42fi4344# Clean up45rm -rf ".usage-rules/.tmp/<package>-<version>"46```4748Mention adding `.usage-rules/` to `.gitignore` once per session when fetching occurs.4950## Context-Aware Extraction5152Usage rules files can be large. Extract relevant sections based on user's question:5354| User Context | Look for Sections |55|--------------|-------------------|56| querying, filters | "Querying", "Filters", "Read Actions" |57| actions, create/update | "Actions", "Changes", "Validations" |58| relationships | "Relationships", "Aggregates" |59| errors, validation | "Error Handling", "Validations" |60| authorization | "Policies", "Authorization" |61| testing | "Testing" |6263Find section headings with line numbers, then extract the relevant section content.6465## Key Behaviors6667- Extract relevant sections, don't dump entire file68- Highlight `# GOOD` vs `# BAD` patterns explicitly69- Note when package doesn't provide usage rules70- Suggest `hex-docs-search` for API documentation (complementary)71- Version awareness: prefer deps/ version over cached
bradleygolden