spec-interview
Skill1 starsChanged 8 months agoMITView on GitHub
Conduct an in-depth interview using the AskUserQuestion tool to elicit a complete specification, then write it to a file. Use whenever the user wants to create a detailed spec, PRD, requirements doc, design brief, or project plan through guided questioning — even when they don't explicitly say "interview" or "spec". Trigger on phrases like "spec out", "help me plan", "let's flesh out", "draft requirements for", "interview me about", "I want to think through", or anytime the user asks for a thorough back-and-forth before writing something down.
10 other projects use a version of this.
Adopted by
Most recently taken up by
- jellydn/my-ai-toolstheir own version, first seen Nov 15, 2026
- mehboobali98/rmine-skillstheir own version, first seen Nov 6, 2026
- sampgreenwell-cyber/claude-skillstheir own version, first seen Oct 13, 2026
- ghostflare76/claude-skillstheir own version, first seen Oct 11, 2026
- AI-Cultivation/cultivation-world-simulatortheir own version, first seen Oct 8, 2026
- 17-sss/agent-skillstheir own version, first seen Sep 22, 2026
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- AI-Cultivation/cultivation-world-simulator★ 2.1ksame name
- 4thfever/cultivation-world-simulator★ 2.1ksame name
- zeuikli/claude-code-workspace★ 155same name
- jellydn/my-ai-tools★ 129same name
- 17-sss/agent-skills★ 2same name
- huminglong/my_claude_skills★ 1same name
- YogirajA/Claude-Skills★ 1same name
- ghostflare76/claude-skills★ 0same name
- mehboobali98/rmine-skills★ 0same name
- sampgreenwell-cyber/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- appunite-brandSkill
- communication-analystSkill
- meeting-memoSkill
- roam-transcript-syncSkill
- shugyo-mcpSkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Use AskUserQuestion exclusively for elicitation.
- Very specific: line 87
Use a filename that reflects the project, kebab-case, .md extension: <project-name>-spec.md (for example, referral-program-spec.md).
- Very specific: line 89
After writing, share the file with a computer:// link and a one-line summary of what it covers.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Spec Interview
Turn a vague idea into a detailed written specification by interviewing the user with the AskUserQuestion tool. The interview keeps going — non-obvious questions, real tradeoffs — until the user says stop. Then write the spec to a file they can refer back to.
Why this works
People rarely have the full spec in their head when they start, and typing every detail into open-ended chat is slow and exhausting. The AskUserQuestion tool changes the dynamic: it presents 2–4 concrete options per question, which surfaces tradeoffs the user hadn't considered and is much faster than free-text. Your job is to feed that strength — ask the questions a thoughtful collaborator would ask after sitting with the problem for ten minutes, not the surface-level ones.
How to run the interview
Use AskUserQuestion exclusively for elicitation. Don't ask questions in plain prose — that loses the structured-choice advantage and slows the user down. Each call can hold 1–4 questions; group related questions into the same call when the user can reasonably consider them together.
Cover the dimensions a real spec needs:
- The problem and who has it (which user, in which moment, what they do today instead)
- Scope boundaries — especially what's out of scope (often more revealing than what's in)
- Technical implementation choices and their tradeoffs (stack, data model, hosting, integrations, auth)
- UX and interaction details (key screens, edge-case flows, empty/error/loading states)
- Concerns and risks (failure modes, scaling cliffs, compliance, abuse, second-order effects)
- Success criteria (how the user will know it worked, in measurable terms)
- Constraints (budget, timeline, team size, existing systems that must be respected)
Make the questions non-obvious
Skip questions where the answer is obvious or doesn't change anything downstream. Aim for questions where each option teaches the user something about their own preferences — concrete forks in the road, not abstract preferences. Some shapes that work:
- Force a real fork. "When two users edit the same row at once: last-write-wins, optimistic locking with a merge prompt, or row-level locking that blocks the second writer?"
- Surface implicit assumptions. "Who pays the third-party API costs — your service, the buyer, or the seller?"
- Make them choose between things they'd both like. "Faster page loads via aggressive caching, or fresher data with no cache — pick the one you'd defend in a meeting."
- Probe failure modes. "If the payments provider is down for an hour, do you queue the orders, fail loudly, or fall back to a secondary provider?"
Avoid asking things you can reasonably infer from earlier answers — that wastes the user's attention. After each round, internalize what you learned and let it shape the next round. If an answer opens a new dimension (regulated data, an unexpected user type, a new integration), follow it.
When to stop
Keep interviewing until the user explicitly says they're done, want to wrap up, or asks for the spec to be written. Don't self-terminate early because the basics feel covered — the value of this skill is going deeper than the user would on their own. If you're running out of new ground, push into areas that usually get skipped: rollback plans, what happens at 10x scale, what gets cut if the timeline halves, who owns the system in six months, what migrations would be painful later.
Writing the spec
Once the user signals stop, write the spec to a file with the Write tool. Use this structure as a starting point and adapt to the project's nature:
# [Project name]
## Overview
One paragraph: what this is, who it's for, why it matters.
## Goals
What success looks like, in concrete terms.
## Non-goals
What's explicitly out of scope and why.
## User stories / scenarios
Specific people doing specific things, including the messy edge cases.
## Functional requirements
What it does, behavior by behavior.
## Technical design
Stack, data model, key services, integrations, deployment.
## UX & interaction design
Key flows, screens, states. Reference decisions made during the interview.
## Risks & open questions
Things that could go wrong, decisions deferred, assumptions to validate.
## Constraints
Timeline, budget, team, existing systems.
## Success metrics
How you'll know it worked.Pull directly from the interview answers — don't invent details to fill space. If a section is genuinely empty because the interview didn't reach it, write (not yet specified — open question) rather than hallucinating content. That honesty is more useful to the user than a polished-looking but fabricated section.
Output location
Write the spec to the user's selected workspace folder if one is connected — that way the file persists on their computer after the session ends. If no folder is connected, write it to the session outputs folder so it can still be linked back to the user.
Use a filename that reflects the project, kebab-case, .md extension: <project-name>-spec.md (for example, referral-program-spec.md). If the project's name is unclear, ask the user before writing rather than guessing.
After writing, share the file with a computer:// link and a one-line summary of what it covers. Don't recap the whole interview — the user just lived through it. They want to read the file, not a meta-narrative about it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

