### Problem/Motivation Tool already exposes everything an agent needs to drive an operation it did not author: ```bash drush tool:search "canvas page" --operation=write drush tool:info canvas_add_component --format=json drush tool:run canvas_add_component --input='{"target_type":"page","target_id":"22","component_id":"sdc.mytheme.card"}' --json ``` Agents do not reach for it. Every consumer module that ships Agent Skills restates the mechanics instead — `canvas_tools` does today: "run `drush tool:run <id> --input=...`", "the same ids are exposed over MCP", plus a hand-copied input example per operation. Those examples drift the moment an input is renamed, and the agent never learns that `tool:info` would have told it the current signature. `drupal/ai_best_practices` syncs `.agents/skills/` from installed modules into the project on `composer install`. `mcp_server` and `canvas_tools` ship skills this way. Tool does not, so the "discover → inspect → run" procedure lives nowhere near the commands it describes. ### Proposed resolution Add `.agents/skills/use-drupal-tools/SKILL.md` per the [Agent Skills specification](https://agentskills.io/specification). Procedural only — the `tool:*` commands stay the source of truth, the skill tells the agent when to call which one: 1. **Find:** `tool:search "<keywords>" [--match=and] [--operation=…]`, `tool:list --operation=…`. Filter by operation kind before reading descriptions: `read`/`explain`/`transform` do not modify, `write`/`trigger` do. 2. **Inspect before running:** `tool:info <id> --format=json`. Input names, data types, `required`, `multiple`, `locked`. Never copy inputs from an example when the definition is one command away. 3. **Run:** `tool:run <id> --input='<json>'` vs repeated `--input=key=value`; `--json` and its `{success, message, outputs}` shape; `--uid` so `checkAccess()` runs as the real user, not uid 1. 4. **Read the result:** outputs are populated only on success. Branch on `success`, not on the exit code alone. 5. **Same operation, other invokers:** the plugin id is the MCP tool name through `mcp_server_tool_bridge` (`mcp_tool_config` entities) and the function name in `tool_ai_connector`. 6. **Gotchas that are open bugs**, so the agent works around them until they land: an `--input` that is neither JSON nor `key=value` is dropped silently, and `tool:info` / `tool:list` / `tool:search` exit 0 on not-found (#3582970); access denial does not surface the reason (#3582991). Step 2 is the payoff of #3582943 — as the schema and requirements surfacing land there, the skill points at `tool:info` and picks them up without a rewrite. Consumer modules then shrink their own skills to domain steps and point at this one for the Tool mechanics. ### Alternatives considered - **Leave it to each consumer module.** Duplicates the boilerplate in every downstream skill; each copy drifts on its own as `tool:*` changes. - **Put it in `drupal/ai_best_practices`.** That repo covers Drupal in general. A procedure tied to this module's commands belongs with the module and releases with it. - **Ship an `author-tool-plugin` skill too** (scaffold a `#[Tool]` plugin, input/output definitions, access, kernel test). Worth doing; separate work item. ### AI usage (if applicable) - [x] **AI Assisted Issue:** This issue was generated with AI assistance, but was reviewed and refined by the creator. - [ ] **AI Assisted Code:** This code was mainly generated by a human, with AI autocompleting or parts AI generated, but under full human supervision. - [x] **AI Generated Code:** This code was mainly generated by an AI with human guidance, and reviewed, tested, and refined by a human. - [ ] **Vibe Coded:** This code was generated by an AI and has only been functionally tested.