UsageRules: Auto-Generated AGENTS.md from Hex Dependencies for Elixir Projects
usage_rules is a dev-only Elixir mix tool (by the Ash Framework team) that gathers usage-rules.md files from Hex dependencies and consolidates them into AGENTS.md and CLAUDE.md files. This gives LLM coding agents automatic context about how to use your project's dependencies correctly. Library authors include a usage-rules.md in their Hex package; consuming projects run mix usage_rules.sync to generate consolidated agent instructions.
`usage_rules` is a dev-only Mix tool created by the Ash Framework team that automates the generation of `AGENTS.md` and `CLAUDE.md` files for Elixir projects by consolidating usage documentation from Hex dependencies. ## How It Works 1. Library authors include a `usage-rules.md` file in their Hex package (must be listed in the `files:` key of `mix.exs`) 2. Consuming projects add `{:usage_rules, "~> 0.x", only: :dev}` to their dependencies 3. Running `mix usage_rules.sync` gathers all `usage-rules.md` files from deps and consolidates them into project-level agent context files 4. The tool also generates per-dependency `SKILL.md` files for Claude Code's skill system The process is idempotent — re-run after dependency changes to update the generated files. Configuration is done in `mix.exs`. ## Why It Matters LLM coding agents (Claude Code, Cursor, GitHub Copilot) work better when they have context about library APIs, conventions, and common patterns. Without usage rules, agents rely on training data that may be outdated or incomplete. With them, agents get library-author-curated instructions that stay current with each dependency version. ## For Library Authors Include a `usage-rules.md` in your package root documenting: preferred API patterns, common mistakes to avoid, configuration conventions, and any non-obvious behavior. Critically, the file must be listed in the `files:` key of your `mix.exs` or it won't be included in the published Hex package.