About agent-interface-design
agent-interface-design is an agent skill for improving tool interfaces based on observed misuse. It focuses on expressive parameters and point-of-use descriptions, while accounting for callers, discoverability, and remaining risks.
Key features
- 01Investigates misuse through logs or feedback
- 02Uses parameters to express valid choices and intent
- 03Keeps behavioral guidance in tool descriptions
- 04Balances resident tools with on-demand discovery
- 05Identifies remaining mistakes and needed guardrails
Use cases
- 01Redesigning a tool that agents misuse
- 02Making tool parameters clearer and invalid states harder to express
Install
Copy the command and run it in a terminal.
$
npx skills add https:/After installing, type/agent-interface-designin Claude Code to confirm it loaded.
Details
From the project READMEAgent interface design
Examples teach one path and quietly fence off the others: shown three ways to call a tool, a model tends to produce those three. A well-designed interface teaches the whole space at once. The parameters say what is possible, the description says what is expected, and there is very little left to write.
Steps
- Find out how the tool is actually being misused before redesigning it. Read transcripts, logs, or the user's complaint. Misuse is an interface symptom first and a documentation symptom second, and the fix is usually a rename or a type, not a paragraph.
- Push meaning into the parameters:
- Enumerate instead of accepting free text. A status of
pending | in_progress | completedteaches the whole state machine without a sentence of prose. - Name for intent rather than implementation, so the right call is the one that reads correctly.
- Make invalid states unrepresentable wherever the type system allows it. A parameter that cannot express a mistake needs no warning about that mistake.
- Enumerate instead of accepting free text. A status of
- Put behavioral instruction in the tool's own description, at the point of use, and only there. The same guidance restated in a global preamble is how a codebase grows contradictions.
- Treat the urge to add a usage example as a diagnostic: it usually means a parameter is underspecified. Fix the interface first. Keep an example only for a format that genuinely cannot be guessed, such as a bespoke query syntax.
- Decide what is resident and what is discoverable. Tools needed on most turns belong in context; tools needed rarely should be findable on demand so they cost nothing until they're wanted.
- Finish by naming the mistake the design still permits, and say whether it is cheap enough to live with or needs an explicit guardrail.
Guardrails
- A description that has to explain what a parameter means is a parameter that needs a better name.
- Irreversible and high-stakes operations are the exception to all of the above: there, explicit constraint and confirmation beat elegance.
- Never redesign a signature without first finding every existing caller.
- Terseness is not the goal; expressiveness is. Cutting a description that carried real behavior is a worse outcome than a description that ran long.
Comments
Markdown supported