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)

1. Project deps: deps/<package>/usage-rules.md
2. Fetched cache: .usage-rules/<package>-<version>/usage-rules.md
3. 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_graphql - spark, 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:

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