O’Reilly Radar published a piece on what they call the toolkit pattern: structuring project documentation around user intent rather than syntax, so that AI can generate valid, working configuration from plain-English descriptions. The idea is that most configuration tools force a trade-off between simple defaults and granular options, and docs written with AI consumption in mind can bridge that gap.
This is not a theoretical exercise. If you build developer tools, CLIs, or anything with configuration files, your users are increasingly interacting with your product through a chat interface. They paste your docs into a context window and ask the model to generate a config. The quality of what comes back depends entirely on how your documentation is structured.
The pattern works because it shifts the documentation from ‘here is every flag and what it does’ to ‘here is what you are trying to accomplish and the flags that matter for that goal’. Intent-based docs are better for humans too, but they are dramatically better for models that need to map a natural language request to a valid output.
The practical takeaway for anyone maintaining developer-facing tools: audit your docs from the perspective of an LLM trying to generate a working configuration. If your docs are organised alphabetically by flag name, they are optimised for reference lookup, not for generation. Reorganising around common tasks and intent patterns is low-effort, high-impact work.
Worth noting that this pattern has limits. It works well for declarative configuration but less well for procedural code where the space of valid outputs is too large to capture in intent-based documentation. Know where the pattern applies before reaching for it everywhere.