⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
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.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Finding-Unknowns Skills
14 installable skills that help your coding agent find what you don't know — before it gets expensive to fix.
The map is not the territory. Your prompt is a map; the codebase and the real world are the territory. The gap between them is your unknowns, and with strong models the quality of the work is bottlenecked by how well you clarify them. The original eight task-level skills turn that idea, from Thariq Shihipar's essay A Field Guide to Fable: Finding Your Unknowns, into commands you can run in Claude Code, OpenAI Codex, Kimi Code CLI (Kimi K3), or any agent that reads the agentskills.io SKILL.md format.
Another three come from his follow-up, The new rules of context engineering for Claude 5 generation models, which works one layer up: not the unknowns in a single prompt, but the ones baked into the context every prompt inherits.
Community project. Twelve skills distilled, with attribution, from public essays by Thariq Shihipar (Anthropic, Claude Code team), plus two maintainer-designed extensions. Not an official Anthropic repository.
The contribution here is the reusable instruction design: focused triggers, concrete deliverables, scope boundaries, portable packaging, and documented checks. The new extensions take the workflow from identifying unknowns to testing them. Examples · Compatibility · Contributing · Roadmap
The idea in one table
| Known | Unknown | |
|---|---|---|
| Known | What's in your prompt | What you know you haven't figured out |
| Unknown | So obvious you'd never write it down, but you'd recognize it on sight | What you haven't considered at all |
Every skill below is a cheap way to move something out of the bottom row before implementation makes it expensive.
The skills
| Skill | Phase | One line |
|---|---|---|
blindspot-pass | Before | Surface your unknown unknowns in an unfamiliar area, then help you prompt better |
brainstorm-prototypes | Before | Throwaway variations you can react to, for taste you can't verbalize |
interview-me | Before | One question at a time, architecture-changing questions first |
reference-hunt | Before | Use working source code as the spec, even across languages |
implementation-plan | Before | A plan that leads with the decisions you're most likely to change |
implementation-notes | During | Log every deviation from the plan so the next attempt learns from this one |
pitch-packager | After | Bundle spec + prototype + notes into a buy-in doc for reviewers |
change-quiz | After | A comprehension quiz you must pass before you merge |
And three for the context itself
The eight above work on one task at a time. These three work on the instructions your agent carries into every task — the layer where Anthropic deleted 80% of Claude Code's system prompt with no measurable loss.
| Skill | One line |
|---|---|
context-audit | Find the contradictions, duplicates, and dead rules in your CLAUDE.md and skills, and cut them |
agent-interface-design | Design tools an agent can't misuse, so you don't have to document them |
progressive-disclosure | Split an oversized skill or spec into an entry file plus files loaded only when needed |
progressive-disclosure ships with disable-model-invocation: true. In Claude Code that makes it user-invoked only — it stays out of the model's reach and costs nothing in your context window until you type its name. Codex ignores the flag (verified on v0.143: the skill and its description still load into the model-visible prompt), so treat it as a normal model-invoked skill there.
Two extensions for evidence
These are maintainer-designed additions, informed by established testing practices. The original eleven skill files are unchanged in the published v1.4.0 release.
| Skill | Phase | One line |
|---|---|---|
assumption-test | Before | Turn a consequential technical assumption into a bounded, falsifiable experiment |
test-blindspots | During / after | Investigate what passing tests do not establish, with focused probes and reproducible evidence |
The additions have packaging and discovery checks. Evaluation protocol and fixtures.
One for proving a bug fix
| Skill | Phase | One line |
|---|---|---|
regression-proof | During / after | Show that the same regression test fails before a fix and passes after it |
Source: Spending your effort.
Use regression-proof for a reported bug; use test-blindspots to investigate what a passing suite misses. For feature work: clarify with interview-me, implement and iterate, then verify relevant behavior. Skills guide the workflow; they do not change your agent's effort setting.
Install
One command, any agent (recommended): Vercel's skills CLI auto-detects your coding agent (Claude Code, Cursor, Codex, Copilot, Gemini, and more) and installs the skills into the right place for each:
npx skills add Neeeophytee/finding-unknowns-skills
Add --list to preview the 14 skills first, or --skill blindspot-pass to install just one. (Discoverable on skills.sh.)
As a Claude Code plugin (all 14 skills):
/plugin marketplace add Neeeophytee/finding-unknowns-skills
/plugin install finding-unknowns@finding-unknowns-skills
Manually (pick the skills you want): copy any skills/<name>/ folder into your project's .claude/skills/ directory (or ~/.claude/skills/ for all projects).
The one-file version: if you'd rather have the whole approach as passive guidance instead of commands, copy guidance/finding-unknowns.md into your project root as CLAUDE.md (Claude Code) or AGENTS.md (Codex and other AGENTS.md-reading agents), or append it to your existing one.
Moved in v1.2.0: this file used to be the repo's own
CLAUDE.md. RootCLAUDE.md/AGENTS.mdnow hold gotchas for maintaining this repo, which is what those files are for — general methodology in a file meant for repo-specific context is exactly the patterncontext-auditflags.
Use in Cursor
The npx skills add Neeeophytee/finding-unknowns-skills command above detects Cursor and installs the skills into ~/.cursor/skills/ for you — no manual step. (Historical receipt: at v1.2.0, `[email protected] -
// HOW IT'S BUILT
KEY FILES