Packages
A config-driven dev tool for Elixir projects to manage AGENTS.md files and agent skills from dependencies
Current section
42 Versions
Jump to
Current section
42 Versions
Compare versions
8
files changed
+1208
additions
-1731
deletions
| @@ -12,6 +12,13 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline | |
| 12 12 | |
| 13 13 | <!-- changelog --> |
| 14 14 | |
| 15 | + ## v1.0.0-rc.0 (2026-02-07) |
| 16 | + ### Breaking Changes: |
| 17 | + |
| 18 | + * rebuild usage rules to be config-driven and support agent skills by Zach Daniel |
| 19 | + |
| 20 | + |
| 21 | + |
| 15 22 | ## v0.1.26 (2025-11-05) |
| @@ -12,251 +12,342 @@ SPDX-License-Identifier: MIT | |
| 12 12 | |
| 13 13 | # UsageRules |
| 14 14 | |
| 15 | - **UsageRules** is a development tool for Elixir projects that: |
| 15 | + **UsageRules** is a config-driven dev tool for Elixir projects that manages your AGENTS.md file and agent skills from dependencies. It: |
| 16 16 | |
| 17 | - - helps gather and consolidate usage rules from dependencies to provide to LLM agents via `mix usage_rules.sync` |
| 18 | - - provides pre-built usage rules for Elixir |
| 19 | - - provides a powerful documentation search task for hexdocs with `mix usage_rules.search_docs` |
| 17 | + - Gathers and consolidates `usage-rules.md` files from your dependencies into an AGENTS.md (or any file) |
| 18 | + - Generates agent skills (SKILL.md files) from dependency usage rules |
| 19 | + - Provides built-in usage rules for Elixir and OTP |
| 20 | + - Includes a powerful documentation search task via `mix usage_rules.search_docs` |
| 20 21 | |
| 21 22 | ## Quickstart |
| 22 23 | |
| 23 | - Begin by installing `usage_rules` in your project. |
| 24 | - If you have [igniter](https://github.com/ash-project/igniter) installed, run: |
| 24 | + ### Installation |
| 25 | + |
| 26 | + If you have [igniter](https://github.com/ash-project/igniter) installed: |
| 25 27 | |
| 26 28 | ```sh |
| 27 29 | mix igniter.install usage_rules |
| 28 30 | ``` |
| 29 31 | |
| 30 | - Otherwise, add `usage_rules` to your dependencies in `mix.exs` and run `mix deps.get`: |
| 31 | - |
| 32 | - ```elixir |
| 33 | - {:usage_rules, "~> 0.1"} |
| 34 | - ``` |
| 35 | - |
| 36 | - Then, use the `usage_rules.sync` mix task to gather rules from your dependencies: |
| 37 | - |
| 38 | - ```sh |
| 39 | - # swap AGENTS.md out for any file you like, e.g `CLAUDE.md` |
| 40 | - # sync projects as links to their usage rules |
| 41 | - # to save tokens. Agent can view them on demand. |
| 42 | - # Existing rules in the file are retained. |
| 43 | - mix usage_rules.sync AGENTS.md --all \ |
| 44 | - --inline usage_rules:all \ |
| 45 | - --link-to-folder deps |
| 46 | - ``` |
| 47 | - |
| 48 | - ## Does it help? |
| 49 | - |
| 50 | - Yes, and we have data to back it up: https://github.com/ash-project/evals/blob/main/reports/flagship.md |
| 51 | - |
| 52 | - You'll note this package itself doesn't have a usage-rules.md. Its a simple tool that likely would not benefit from having a usage-rules.md file. |
| 53 | - |
| 54 | - `usage-rules.md` is not an existing standard, rather it is a community initiative that may evolve over time as adoption grows and feedback is gathered. We encourage experimentation and welcome input on how to make this approach more useful for the broader Elixir ecosystem. |
| 55 | - |
| 56 | - ## For Package Authors |
| 57 | - |
| 58 | - Even if you don't want to use LLMs, its very possible that your users will, and they will often come to you with hallucinations from their LLMs and try to get your help with it. Writing a `usage-rules.md` file is a great way to stop this sort of thing 😁 |
| 59 | - |
| 60 | - We don't really know what makes great usage-rules.md files yet. Ash Framework is experimenting with quite fleshed out usage rules which seems to be working quite well. See [Ash Framework's usage-rules.md](https://github.com/ash-project/ash/blob/main/usage-rules.md) for one such large example. Perhaps for your package or framework only a few lines are necessary. We will all have to adjust over time. |
| 61 | - |
| 62 | - One quick tip is to have an agent begin the work of writing rules for you, by pointing it at your docs and asking it to write a `usage-rules.md` file in a condensed format that would be useful for agents to work with your tool. Then, aggressively prune and edit it to your taste. |
| 63 | - |
| 64 | - Make sure that your `usage-rules.md` file is included in your hex package's `files` option, so that it is distributed with your package. |
| 65 | - |
| 66 | - ### Sub rules |
| 67 | - |
| 68 | - A package can have a `package-rules.md` and/or sub-rule files, each of which is referred to separately. |
| 69 | - For example: |
| 70 | - |
| 71 | - ``` |
| 72 | - package-rules.md # general rules |
| 73 | - package-rules/ |
| 74 | - html.md # html specific rules |
| 75 | - database.md # database specific rules |
| 76 | - ``` |
| 77 | - |
| 78 | - When synchronizing, these are stated separately, like so: |
| 79 | - |
| 80 | - ``` |
| 81 | - mix usage_rules.sync AGENTS.md package package:html package:database |
| 82 | - ``` |
| 83 | - |
| 84 | - ## Key Features |
| 85 | - |
| 86 | - 1. **Dependency Rules Collection**: Automatically discovers and collects usage rules from dependencies that provide `usage-rules.md` files in their package directory |
| 87 | - 2. **Rules Consolidation**: Combines multiple package rules into a single file with proper sectioning and markers |
| 88 | - 3. **Status Tracking**: Can list dependencies with usage rules and check if your consolidated file is up-to-date |
| 89 | - 4. **Selective Management**: Allows adding/removing specific packages from your rules file |
| 90 | - 5. **Documentation Search**: Search hexdocs with human-readable markdown output using `mix usage_rules.search_docs` - designed to help AI agents find relevant documentation |
| 91 | - |
| 92 | - ## How It Works |
| 93 | - |
| 94 | - 1. The tool scans your project's dependencies (in `deps/` directory) |
| 95 | - 2. Looks for `usage-rules.md` files in each dependency |
| 96 | - 3. Consolidates these rules into a target file with special markers like `<-- package-name-start -->` and `<-- package-name-end -->` |
| 97 | - 4. Maintains sections that can be updated independently as dependencies change |
| 98 | - |
| 99 | - This is particularly useful for projects using frameworks like Ash, Phoenix, or other packages that provide specific usage guidelines, coding patterns, or best practices that should be followed consistently across your project. |
| 100 | - |
| 101 | - > **Note:** UsageRules can only discover `usage-rules.md` files from dependency versions that actually include them. If a package has added usage rules in a newer version than what your project uses, you'll need to update that dependency to access its rules. |
| 102 | - |
| 103 | - ## Usage |
| 104 | - |
| 105 | - The main task `mix usage_rules.sync` provides several modes of operation: |
| 106 | - |
| 107 | - ### Standard usage (recommended) |
| 108 | - |
| 109 | - There are two standard ways to use usage_rules. The first, is to copy usage rules into your project. This allows customization and visibility into the rules. The second is to use the rules files directly from the deps in your `deps/` folder. In both cases, your rules file is modified to link to the usage rules files, as a breadcrumb to the agent. |
| 110 | - |
| 111 | - #### Copying into your project |
| 112 | - |
| 113 | - This will create a folder called `rules`, with a file per package that has a `usage-rules.md` file. Then it will link |
| 114 | - to those from you rules file. |
| 115 | - |
| 116 | - ```sh |
| 117 | - mix usage_rules.sync AGENTS.md --all \ |
| 118 | - --link-to-folder deps \ |
| 119 | - --inline usage_rules:all |
| 120 | - ``` |
| 121 | - |
| 122 | - #### Using deps folder |
| 123 | - |
| 124 | - This will add a section in your rules file for each of your top level dependencies that have a `usage-rules.md`. It is |
| 125 | - simply a breadcrumb to tell the agent that it should look |
| 126 | - in `deps/<package-name>/usage-rules.md` when working with |
| 127 | - that package. This will not overwrite your existing rules, but will append to it, and future calls will synchronize those contents. |
| 128 | - |
| 129 | - ```sh |
| 130 | - mix usage_rules.sync CLAUDE.md --all --link-to-folder deps |
| 131 | - ``` |
| 132 | - |
| 133 | - ### Combine specific packages |
| 134 | - ```sh |
| 135 | - mix usage_rules.sync rules.md ash phoenix |
| 136 | - ``` |
| 137 | - |
| 138 | - ### Gather all dependencies with usage rules |
| 139 | - ```sh |
| 140 | - mix usage_rules.sync CLAUDE.md --all |
| 141 | - ``` |
| 142 | - |
| 143 | - ### List available packages with usage rules |
| 144 | - ```sh |
| 145 | - mix usage_rules.sync --list |
| 146 | - ``` |
| 147 | - |
| 148 | - ### Check status against a file |
| 149 | - ```sh |
| 150 | - mix usage_rules.sync CLAUDE.md --list |
| 151 | - ``` |
| 152 | - |
| 153 | - ### Remove packages from a file |
| 154 | - ```sh |
| 155 | - mix usage_rules.sync CLAUDE.md ash --remove |
| 156 | - ``` |
| 157 | - |
| 158 | - ### Use folder links for better organization |
| 159 | - ```sh |
| 160 | - mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder rules |
| 161 | - ``` |
| 162 | - |
| 163 | - ### Use @-style folder links |
| 164 | - ```sh |
| 165 | - mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder rules --link-style at |
| 166 | - ``` |
| 167 | - |
| 168 | - ### Link directly to deps files |
| 169 | - ```sh |
| 170 | - mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder deps |
| 171 | - ``` |
| 172 | - |
| 173 | - ### Gather all dependencies with folder links |
| 174 | - ```sh |
| 175 | - mix usage_rules.sync CLAUDE.md --all --link-to-folder docs |
| 176 | - ``` |
| 177 | - |
| 178 | - ### Documentation Search (`mix usage_rules.search_docs`) |
| 179 | - |
| 180 | - The `mix usage_rules.search_docs` task searches hexdocs with human-readable markdown output, specifically designed to help AI agents find relevant documentation. |
| 181 | - |
| 182 | - ```sh |
| 183 | - # Search documentation for all dependencies in the current mix project |
| 184 | - mix usage_rules.search_docs "search term" |
| 185 | - |
| 186 | - # Search documentation for specific packages |
| 187 | - mix usage_rules.search_docs "search term" -p ecto -p ash |
| 188 | - |
| 189 | - # Search documentation for specific versions |
| 190 | - mix usage_rules.search_docs "search term" -p ecto@3.13.2 -p ash@3.5.26 |
| 191 | - |
| 192 | - # Control output format and pagination |
| 193 | - mix usage_rules.search_docs "search term" --output json --page 2 --per-page 20 |
| 194 | - |
| 195 | - # Search across all packages on hex |
| 196 | - mix usage_rules.search_docs "search term" --everywhere |
| 197 | - |
| 198 | - # Search only in titles (useful for finding specific functions/modules) |
| 199 | - mix usage_rules.search_docs "Enum.zip" --query-by title |
| 200 | - |
| 201 | - # Search in specific fields (available: doc, title, type) |
| 202 | - mix usage_rules.search_docs "validation" --query-by "doc,title" |
| 203 | - ``` |
| 204 | - |
| 205 | - ## Advanced Features |
| 206 | - |
| 207 | - ### Folder Links (`--link-to-folder`) |
| 208 | - |
| 209 | - Organizes usage rules into separate files for better management of large rule sets. |
| 210 | - |
| 211 | - **Options:** |
| 212 | - - `--link-style markdown` (default): `[ash usage rules](docs/ash.md)` |
| 213 | - - `--link-style at`: `@docs/ash.md` (optimized for Claude AI) |
| 214 | - - `--link-to-folder deps`: Links directly to `deps/package/usage-rules.md` (no file copying) |
| 215 | - |
| 216 | - **Examples:** |
| 217 | - ```sh |
| 218 | - # Create individual files with markdown links |
| 219 | - mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder docs |
| 220 | - |
| 221 | - # Use @-style links for Claude AI |
| 222 | - mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder docs --link-style at |
| 223 | - |
| 224 | - # Link directly to deps without copying |
| 225 | - mix usage_rules.sync CLAUDE.md ash phoenix --link-to-folder deps |
| 226 | - ``` |
| 227 | - |
| 228 | - ## Installation |
| 229 | - |
| 230 | - ### With Igniter |
| 231 | - |
| 232 | - `mix igniter.install usage_rules`. |
| 233 | - |
| 234 | - Add the dependency manually |
| 32 | + Or add `usage_rules` manually to your `mix.exs`: |
| 235 33 | |
| 236 34 | ```elixir |
| 237 35 | def deps do |
| 238 36 | [ |
| 239 | - # should only ever be used as a dev dependency |
| 240 | - # requires igniter as a dev dependency |
| 241 | - {:usage_rules, "~> 0.1", only: [:dev]}, |
| 37 | + {:usage_rules, "~> 0.2", only: [:dev]}, |
| 242 38 | {:igniter, "~> 0.6", only: [:dev]} |
| 243 39 | ] |
| 244 40 | end |
| 245 41 | ``` |
| 246 42 | |
| 247 | - ### Alias example |
| 43 | + ### Configuration |
| 44 | + |
| 45 | + All configuration lives in your `mix.exs` project config. Add a `:usage_rules` key: |
| 248 46 | |
| 249 47 | ```elixir |
| 250 | - defp aliases do |
| 251 | - [ |
| 252 | - "usage_rules.update": [ |
| 253 | - """ |
| 254 | - usage_rules.sync AGENTS.md --all \ |
| 255 | - --inline usage_rules:all \ |
| 256 | - --link-to-folder deps |
| 257 | - """ |
| 258 | - |> String.trim() |
| 259 | - ] |
| 260 | - ] |
| 261 | - end |
| 48 | + def project do |
| 49 | + [ |
| 50 | + app: :my_app, |
| 51 | + # ... |
| 52 | + usage_rules: usage_rules() |
| 53 | + ] |
| 54 | + end |
| 55 | + |
| 56 | + defp usage_rules do |
| 57 | + [ |
| 58 | + file: "AGENTS.md", |
| 59 | + usage_rules: :all, |
| 60 | + link_to_folder: "deps" |
| 61 | + ] |
| 62 | + end |
| 262 63 | ``` |
| 64 | + |
| 65 | + Then run: |
| 66 | + |
| 67 | + ```sh |
| 68 | + mix usage_rules.sync |
| 69 | + ``` |
| 70 | + |
| 71 | + That's it. The config is the source of truth — packages in the file but not in config are automatically removed on each sync. |
| 72 | + |
| 73 | + ## Configuration Reference |
| 74 | + |
| 75 | + ```elixir |
| 76 | + defp usage_rules do |
| 77 | + [ |
| 78 | + # The file to write usage rules into (required for usage_rules syncing) |
| 79 | + file: "AGENTS.md", |
| 80 | + |
| 81 | + # Which packages to include (required for usage_rules syncing) |
| 82 | + # :all discovers every dependency with a usage-rules.md |
| 83 | + usage_rules: :all, |
| 84 | + # Or list specific packages and sub-rules: |
| 85 | + # usage_rules: [ |
| 86 | + # :ash, # main usage-rules.md |
| 87 | + # "phoenix:ecto", # specific sub-rule |
| 88 | + # :elixir, # built-in Elixir rules |
| 89 | + # :otp, # built-in OTP rules |
| 90 | + # ], |
| 91 | + |
| 92 | + # Link style instead of inlining full content (recommended) |
| 93 | + link_to_folder: "deps", # links to deps/<pkg>/usage-rules.md |
| 94 | + # link_to_folder: "rules", # copies files into rules/ folder and links there |
| 95 | + link_style: "markdown", # "markdown" (default) or "at" for @-style links |
| 96 | + |
| 97 | + # Force-inline specific packages even when using link_to_folder |
| 98 | + inline: ["usage_rules:all"], |
| 99 | + |
| 100 | + # Agent skills configuration |
| 101 | + skills: [ |
| 102 | + location: ".claude/skills", # where to output skills (default) |
| 103 | + |
| 104 | + # Auto-build a "use-<pkg>" skill per dependency |
| 105 | + deps: [:ash, :req], |
| 106 | + # Supports regex for matching multiple deps: |
| 107 | + # deps: [~r/^ash_/], |
| 108 | + |
| 109 | + # Compose custom skills from multiple packages |
| 110 | + build: [ |
| 111 | + "ash-expert": [ |
| 112 | + description: "Expert on the Ash Framework ecosystem.", |
| 113 | + usage_rules: [:ash, :ash_postgres, :ash_phoenix] |
| 114 | + ] |
| 115 | + ] |
| 116 | + # build also supports regex in usage_rules: |
| 117 | + # build: [ |
| 118 | + # "ash-expert": [ |
| 119 | + # description: "Expert on Ash.", |
| 120 | + # usage_rules: [:ash, ~r/^ash_/] |
| 121 | + # ] |
| 122 | + # ] |
| 123 | + ] |
| 124 | + ] |
| 125 | + end |
| 126 | + ``` |
| 127 | + |
| 128 | + ### Config options |
| 129 | + |
| 130 | + | Option | Type | Description | |
| 131 | + |--------|------|-------------| |
| 132 | + | `file` | `string` | Target file for usage rules (e.g. `"AGENTS.md"`, `"CLAUDE.md"`) | |
| 133 | + | `usage_rules` | `:all \| list` | Which packages to sync. `:all` auto-discovers, or list specific packages | |
| 134 | + | `link_to_folder` | `string \| nil` | Create links instead of inlining. `"deps"` links to dep sources directly | |
| 135 | + | `link_style` | `"markdown" \| "at"` | Link format. `"at"` uses `@path` style (default: `"markdown"`) | |
| 136 | + | `inline` | `list` | Force-inline specific packages when using `link_to_folder` | |
| 137 | + | `skills` | `keyword` | Agent skills configuration (see below) | |
| 138 | + |
| 139 | + ### Skills options |
| 140 | + |
| 141 | + | Option | Type | Description | |
| 142 | + |--------|------|-------------| |
| 143 | + | `location` | `string` | Output directory for skills (default: `".claude/skills"`) | |
| 144 | + | `deps` | `list` | Auto-build a `use-<pkg>` skill per listed dependency. Supports atoms and regexes | |
| 145 | + | `build` | `keyword` | Define custom composed skills from multiple packages' usage rules | |
| 146 | + |
| 147 | + ## Usage Rules |
| 148 | + |
| 149 | + ### Sync all dependencies |
| 150 | + |
| 151 | + The simplest setup — discover all deps with `usage-rules.md` and link to them: |
| 152 | + |
| 153 | + ```elixir |
| 154 | + defp usage_rules do |
| 155 | + [ |
| 156 | + file: "AGENTS.md", |
| 157 | + usage_rules: :all, |
| 158 | + link_to_folder: "deps" |
| 159 | + ] |
| 160 | + end |
| 161 | + ``` |
| 162 | + |
| 163 | + ### Specific packages |
| 164 | + |
| 165 | + Pick exactly which packages to include: |
| 166 | + |
| 167 | + ```elixir |
| 168 | + defp usage_rules do |
| 169 | + [ |
| 170 | + file: "AGENTS.md", |
| 171 | + usage_rules: [:ash, :phoenix, :ecto], |
| 172 | + link_to_folder: "deps" |
| 173 | + ] |
| 174 | + end |
| 175 | + ``` |
| 176 | + |
| 177 | + ### Sub-rules |
| 178 | + |
| 179 | + Packages can provide sub-rules in a `usage-rules/` directory. Reference them with `"package:sub_rule"` syntax: |
| 180 | + |
| 181 | + ```elixir |
| 182 | + usage_rules: [:phoenix, "phoenix:ecto", "phoenix:html"] |
| 183 | + ``` |
| 184 | + |
| 185 | + Use `"package:all"` to include all sub-rules from a package: |
| 186 | + |
| 187 | + ```elixir |
| 188 | + usage_rules: [:phoenix, "phoenix:all"] |
| 189 | + ``` |
| 190 | + |
| 191 | + ### Built-in aliases |
| 192 | + |
| 193 | + UsageRules ships with built-in rules for Elixir and OTP: |
| 194 | + |
| 195 | + ```elixir |
| 196 | + usage_rules: [:elixir, :otp, :ash, :phoenix] |
| 197 | + ``` |
| 198 | + |
| 199 | + ### Inline with folder links |
| 200 | + |
| 201 | + When using `link_to_folder`, you can force specific packages to be inlined: |
| 202 | + |
| 203 | + ```elixir |
| 204 | + defp usage_rules do |
| 205 | + [ |
| 206 | + file: "AGENTS.md", |
| 207 | + usage_rules: [:ash, :phoenix, :usage_rules], |
| 208 | + link_to_folder: "deps", |
| 209 | + inline: ["usage_rules:all"] # inline the usage_rules package's built-in rules |
| 210 | + ] |
| 211 | + end |
| 212 | + ``` |
| 213 | + |
| 214 | + ## Agent Skills |
| 215 | + |
| 216 | + Skills are SKILL.md files that agent tools like Claude Code can discover and use. UsageRules can automatically generate skills from your dependencies' usage rules. |
| 217 | + |
| 218 | + ### Auto-build skills from deps |
| 219 | + |
| 220 | + The `deps` option auto-builds a `use-<package>` skill for each listed dependency: |
| 221 | + |
| 222 | + ```elixir |
| 223 | + defp usage_rules do |
| 224 | + [ |
| 225 | + file: "AGENTS.md", |
| 226 | + usage_rules: :all, |
| 227 | + link_to_folder: "deps", |
| 228 | + skills: [ |
| 229 | + deps: [:ash, :req] |
| 230 | + ] |
| 231 | + ] |
| 232 | + end |
| 233 | + ``` |
| 234 | + |
| 235 | + This generates `.claude/skills/use-ash/SKILL.md` and `.claude/skills/use-req/SKILL.md`, each containing the package's usage rules, available mix tasks, doc search commands, and sub-rule references. |
| 236 | + |
| 237 | + ### Compose custom skills |
| 238 | + |
| 239 | + The `build` option lets you compose a single skill from multiple packages: |
| 240 | + |
| 241 | + ```elixir |
| 242 | + skills: [ |
| 243 | + build: [ |
| 244 | + "ash-expert": [ |
| 245 | + description: "Expert on the Ash Framework ecosystem.", |
| 246 | + usage_rules: [:ash, :ash_postgres, :ash_phoenix, :ash_json_api] |
| 247 | + ] |
| 248 | + ] |
| 249 | + ] |
| 250 | + ``` |
| 251 | + |
| 252 | + This generates a single `.claude/skills/ash-expert/SKILL.md` that combines usage rules from all listed packages. Regex is also supported: |
| 253 | + |
| 254 | + ```elixir |
| 255 | + skills: [ |
| 256 | + build: [ |
| 257 | + "ash-expert": [ |
| 258 | + description: "Expert on Ash.", |
| 259 | + usage_rules: [:ash, ~r/^ash_/] |
| 260 | + ] |
| 261 | + ] |
| 262 | + ] |
| 263 | + ``` |
| 264 | + |
| 265 | + ### Stale skill cleanup |
| 266 | + |
| 267 | + Skills generated by UsageRules include a `managed-by: usage-rules` marker in their YAML frontmatter. When a skill is removed from your config and you re-run `mix usage_rules.sync`, the stale skill files are automatically cleaned up. |
| 268 | + |
| 269 | + ### Skills-only mode |
| 270 | + |
| 271 | + You can use skills without syncing usage rules into a file — just omit the `file` and `usage_rules` keys: |
| 272 | + |
| 273 | + ```elixir |
| 274 | + defp usage_rules do |
| 275 | + [ |
| 276 | + skills: [ |
| 277 | + deps: [:ash, :phoenix] |
| 278 | + ] |
| 279 | + ] |
| 280 | + end |
| 281 | + ``` |
| 282 | + |
| 283 | + ## Documentation Search |
| 284 | + |
| 285 | + `mix usage_rules.search_docs` searches hexdocs with human-readable markdown output, designed for both humans and AI agents. |
| 286 | + |
| 287 | + ```sh |
| 288 | + # Search all project dependencies |
| 289 | + mix usage_rules.search_docs "search term" |
| 290 | + |
| 291 | + # Search specific packages |
| 292 | + mix usage_rules.search_docs "search term" -p ecto -p ash |
| 293 | + |
| 294 | + # Search specific versions |
| 295 | + mix usage_rules.search_docs "search term" -p ecto@3.13.2 |
| 296 | + |
| 297 | + # Search all packages on hex |
| 298 | + mix usage_rules.search_docs "search term" --everywhere |
| 299 | + |
| 300 | + # JSON output |
| 301 | + mix usage_rules.search_docs "search term" --output json |
| 302 | + |
| 303 | + # Search only in titles |
| 304 | + mix usage_rules.search_docs "search term" --query-by title |
| 305 | + |
| 306 | + # Pagination |
| 307 | + mix usage_rules.search_docs "search term" --page 2 --per-page 20 |
| 308 | + ``` |
| 309 | + |
| 310 | + ## For Package Authors |
| 311 | + |
| 312 | + Even if you don't use LLMs yourself, your users likely do. Writing a `usage-rules.md` file helps prevent hallucination-driven support requests. |
| 313 | + |
| 314 | + We don't really know what makes great usage-rules.md files yet. Ash Framework is experimenting with quite fleshed out usage rules which seems to be working quite well. See [Ash Framework's usage-rules.md](https://github.com/ash-project/ash/blob/main/usage-rules.md) for one such large example. Perhaps for your package only a few lines are necessary. |
| 315 | + |
| 316 | + One quick tip is to have an agent begin the work of writing rules for you, by pointing it at your docs and asking it to write a `usage-rules.md` file in a condensed format that would be useful for agents to work with your tool. Then, aggressively prune and edit it to your taste. |
| 317 | + |
| 318 | + Make sure that your `usage-rules.md` file is included in your hex package's `files` option, so that it is distributed with your package. |
| 319 | + |
| 320 | + ### Sub-rules |
| 321 | + |
| 322 | + A package can provide a main `usage-rules.md` and/or sub-rule files: |
| 323 | + |
| 324 | + ``` |
| 325 | + usage-rules.md # general rules |
| 326 | + usage-rules/ |
| 327 | + html.md # html specific rules |
| 328 | + database.md # database specific rules |
| 329 | + ``` |
| 330 | + |
| 331 | + ### Migrating from v0.1 |
| 332 | + |
| 333 | + v0.2 replaces CLI arguments with project config. If you were running: |
| 334 | + |
| 335 | + ```sh |
| 336 | + mix usage_rules.sync AGENTS.md --all --link-to-folder deps |
| 337 | + ``` |
| 338 | + |
| 339 | + Replace it with config in `mix.exs`: |
| 340 | + |
| 341 | + ```elixir |
| 342 | + def project do |
| 343 | + [ |
| 344 | + usage_rules: [ |
| 345 | + file: "AGENTS.md", |
| 346 | + usage_rules: :all, |
| 347 | + link_to_folder: "deps" |
| 348 | + ] |
| 349 | + ] |
| 350 | + end |
| 351 | + ``` |
| 352 | + |
| 353 | + Then just run `mix usage_rules.sync` with no arguments. |
| @@ -5,13 +5,11 @@ | |
| 5 5 | {<<"Forum">>, |
| 6 6 | <<"https://elixirforum.com/c/elixir-framework-forums/ash-framework-forum">>}, |
| 7 7 | {<<"GitHub">>,<<"https://github.com/ash-project/usage_rules">>}, |
| 8 | - {<<"REUSE Compliance">>, |
| 9 | - <<"https://api.reuse.software/info/github.com/ash-project/usage_rules">>}, |
| 10 8 | {<<"Website">>,<<"https://ash-hq.org">>}]}. |
| 11 9 | {<<"name">>,<<"usage_rules">>}. |
| 12 | - {<<"version">>,<<"0.1.26">>}. |
| 10 | + {<<"version">>,<<"1.0.0-rc.0">>}. |
| 13 11 | {<<"description">>, |
| 14 | - <<"A dev tool for Elixir projects to gather LLM usage rules from dependencies">>}. |
| 12 | + <<"A config-driven dev tool for Elixir projects to manage AGENTS.md files and agent skills from dependencies">>}. |
| 15 13 | {<<"elixir">>,<<"~> 1.18">>}. |
| 16 14 | {<<"files">>, |
| 17 15 | [<<"lib">>,<<"lib/mix">>,<<"lib/mix/tasks">>, |
| @@ -50,23 +50,30 @@ if Code.ensure_loaded?(Igniter) do | |
| 50 50 | def igniter(igniter) do |
| 51 51 | igniter |
| 52 52 | |> Igniter.add_notice(""" |
| 53 | - Usage Rules: Sync usage rules for the packages you use. |
| 53 | + UsageRules: Manage your AGENTS.md file and agent skills from dependencies. |
| 54 54 | |
| 55 | - Suggested starting point to sync all usage rules: |
| 55 | + Add configuration to your mix.exs project/0: |
| 56 56 | |
| 57 | - mix usage_rules.sync AGENTS.md --all \\ |
| 58 | - --inline usage_rules:all \\ |
| 59 | - --link-to-folder deps |
| 57 | + def project do |
| 58 | + [ |
| 59 | + usage_rules: usage_rules() |
| 60 | + ] |
| 61 | + end |
| 60 62 | |
| 61 | - Or sync only a specific set, copying their rules to a |
| 62 | - specific folder |
| 63 | + defp usage_rules do |
| 64 | + [ |
| 65 | + file: "AGENTS.md", |
| 66 | + usage_rules: :all, |
| 67 | + link_to_folder: "deps", |
| 68 | + link_style: "markdown" |
| 69 | + ] |
| 70 | + end |
| 63 71 | |
| 64 | - mix usage_rules.sync AGENTS.md \\ |
| 65 | - ash ash_postgres \\ |
| 66 | - --link-to-folder rules |
| 72 | + Then run: |
| 67 73 | |
| 74 | + mix usage_rules.sync |
| 68 75 | |
| 69 | - For more info and examples: `mix help usage_rules.sync` |
| 76 | + For more info: `mix help usage_rules.sync` |
| 70 77 | """) |
| 71 78 | end |
| @@ -15,9 +15,9 @@ defmodule Mix.Tasks.UsageRules.SearchDocs do | |
| 15 15 | current mix project, defaults to the latest version. |
| 16 16 | ## Search documentation for all dependencies in the current mix project |
| 17 17 | $ mix usage_rules.search_docs "search term" |
| 18 | - ## Search documentation for specific packages |
| 18 | + ## Search documentation for specific packages |
| 19 19 | $ mix usage_rules.search_docs "search term" -p ecto -p ash |
| 20 | - ## Search documentation for specific versions |
| 20 | + ## Search documentation for specific versions |
| 21 21 | $ mix usage_rules.search_docs "search term" -p ecto@3.13.2 -p ash@3.5.26 |
| 22 22 | ## Control output format and pagination |
| 23 23 | $ mix usage_rules.search_docs "search term" --output json --page 2 --per-page 20 |
| @@ -225,8 +225,8 @@ defmodule Mix.Tasks.UsageRules.SearchDocs do | |
| 225 225 | result = """ |
| 226 226 | ## #{global_index}. #{title_display} |
| 227 227 | |
| 228 | - **Package:** #{package} |
| 229 | - **Type:** #{type} |
| 228 | + **Package:** #{package} |
| 229 | + **Type:** #{type} |
| 230 230 | **Reference:** #{ref} |
| 231 231 | |
| 232 232 | """ |
| @@ -435,7 +435,7 @@ defmodule Mix.Tasks.UsageRules.SearchDocs do | |
| 435 435 | defp raise_bad_args! do |
| 436 436 | Mix.raise(""" |
| 437 437 | Must provide a search term. For example: |
| 438 | - $ mix hex.docs.search "search term" |
| 438 | + $ mix usage_rules.search_docs "search term" |
| 439 439 | """) |
| 440 440 | end |
| 441 441 | end |
Loading more files…