agent-interface-design
Design tools, scripts, and CLIs that an agent will call, so the interface teaches its own use instead of a wall of prose and examples. Use when building an MCP server or tool definition, writing an agent-facing script, or when an agent keeps misusing a tool it already has.
npx skills add Neeeophytee/finding-unknowns-skills --skill agent-interface-design --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Agent 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 1. 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. 2. Push meaning into the parameters: - Enumerate instead of accepting free text. A status of `pending | in_progress | completed` teaches 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. 3. 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 gr
- Steps
- Guardrails
What does the agent-interface-design skill do?
Design tools, scripts, and CLIs that an agent will call, so the interface teaches its own use instead of a wall of prose and examples. Use when building an MCP server or tool definition, writing an agent-facing script, or when an agent keeps misusing a tool it already has.
How do I install it?
Run `npx skills add Neeeophytee/finding-unknowns-skills --skill agent-interface-design --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From Neeeophytee/finding-unknowns-skills, a repository with 298 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.