hyper-interview skill
✓ VerifiedClarifies vague ideas through a Socratic interview to generate a structured requirement specification file.
- GitHub stars
- 5
- Files
- 1
- Last commit
- Nov 9, 2026
- License
- MIT
- Allowed tools
- —
What does the hyper-interview skill do?
hyper-interview clarifies vague ideas through a Socratic interview to generate a structured requirement specification file.
Summary generated from the skill's SKILL.md.
About the hyper-interview skill
Clarifying vague project ideas through a Socratic interview is what hyper-interview enables for developers. When a user provides an under-specified concept, this skill initiates a conversational process that asks exactly one targeted question at a time to resolve ambiguity regarding goals, constraints, success criteria, and existing code context. It is designed to prevent agents from making guesses during the planning phase by ensuring requirements are fully understood before any implementation begins.
The process starts by using the Explore agent to determine if the project is greenfield or brownfield. For brownfield projects, the skill cites specific file paths or symbols to ground its questions in the existing codebase. Once the interview reaches sufficient clarity, the skill generates a structured markdown specification file in the .hyperclaude/specs/ directory. This file serves as the essential input for subsequent stages like hyper-research or hyper-plan, maintaining a linked trace through a consistent slug system. The skill acts as a mandatory gate, requiring user approval of the specification before any coding or task decomposition occurs.
What an agent can do with it
- 1Refine a vague feature ideaAn AI agent can use this to interview a user who is unsure of their exact requirements for a new feature.
- 2Map requirements to existing codeDevelopers can clarify how a new requirement should integrate with their current brownfield codebase.
- 3Decide between technical approachesWhen a design fork exists, the skill presents multiple options with trade-offs for the user to select.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the hyper-interview skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the hyper-interview skill in Plugin
/plugin marketplace add zeikar/hyperclaude /plugin install hyperclaude@hyperclaude
Install the hyper-interview skill in Claude Code
~/.claude/skills/hyper-interview/SKILL.md
$ npx degit zeikar/hyperclaude/skills/hyper-interview ~/.claude/skills/hyper-interviewInstall the hyper-interview skill in Claude Code (project)
.claude/skills/hyper-interview/SKILL.md
$ npx degit zeikar/hyperclaude/skills/hyper-interview .claude/skills/hyper-interviewInstall the hyper-interview skill in Codex
~/.agents/skills/hyper-interview/SKILL.md
$ npx degit zeikar/hyperclaude/skills/hyper-interview ~/.agents/skills/hyper-interviewInstall the hyper-interview skill in Gemini CLI
~/.gemini/skills/hyper-interview/SKILL.md
$ npx degit zeikar/hyperclaude/skills/hyper-interview ~/.gemini/skills/hyper-interviewInstall the hyper-interview skill in Claude.ai
npx degit zeikar/hyperclaude/skills/hyper-interview hyper-interview && zip -r hyper-interview.zip hyper-interview # claude.ai → Customize → Skills → + → Create skill → Upload a skill → hyper-interview.zip
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablezeikar/hyperclaude/skills/hyper-interview is public and reachablegithub.com/zeikar/hyperclaude/tree/HEAD/skills/hyper-intervi ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-09github.com/zeikar/hyperclaude/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/zeikar/hyperclaude/blob/HEAD/skills/hyper-intervi ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/zeikar/hyperclaude/blob/HEAD/skills/hyper-intervi ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 135 linesgithub.com/zeikar/hyperclaude/blob/HEAD/skills/hyper-intervi ↗Pass
SKILL.md
View on GitHubhyper-interview
Requirements-clarification gate. Turns a vague idea into a clear spec through a short Socratic interview — one targeted question at a time, aimed at whichever requirement dimension is least clear — then writes the spec to .hyperclaude/specs/<YYYYMMDD-HHMM>-<slug>.md. The spec is the front-end input to hyper-research / hyper-plan; the slug it mints is derived from the idea text the same way those skills derive theirs, so handing the same idea forward keeps the research → plan → plan-review trace linked.
Claude-only — no Codex. Critique belongs downstream, where it has something concrete to critique (hyper-plan-review on the plan, hyper-code-review on the diff). This gate's job is clarity, not review: get the requirements right so the plan isn't built on guesses. Anything off in the spec is caught when the plan is reviewed.
This is a light interview: a conversational flow that aims each question at the least-clear requirement dimension, judged qualitatively, with no state kept beyond the spec file.
When to use
- User typed
/hyperclaude:hyper-interview <idea>. - The idea is vague or under-specified and jumping straight to a plan would guess at scope ("interview me", "ask me what you need", "not sure exactly what I want", "make sure you understand before building").
Skip when:
- The request is already concrete (file paths, function names, acceptance criteria) — go to
hyper-plan, or dispatchimplementerfor one step (passrun_in_background: falsefor the result inline). - The user pasted a PRD / spec / plan and wants it executed — use
hyper-plan/hyper-implement. - The user says "just do it" / "skip the questions" — respect it. Don't interrogate; proceed to the work they asked for.
How to invoke
--resume is not supported. Refine in place during the session (Step 5 overwrites the file written in Step 4); a separate fresh run mints a new timestamped spec (same slug if the idea is unchanged) — there's no resume keyed on the path, so that's harmless.
Invocation argument: $ARGUMENTS
Step 1 — Resolve the idea + project context
- The idea is
$ARGUMENTS. If empty, fall back to the user's most recent build/implement intent in this conversation; if none exists, ask "What do you want to build?" and stop. - Greenfield vs brownfield. Dispatch the
Exploreagent (read-only) ONCE withrun_in_background: false(the greenfield/brownfield verdict and area map gate Step 2's questions, which cite Explore's findings; result awaited inline) to check whether the cwd has source code bearing on the idea:- Relevant code exists → brownfield: have Explore map the relevant area (paths, key symbols, patterns) so the questions can cite repo evidence instead of asking the user what the code already reveals.
- Otherwise → greenfield.
- Keep this to a single Explore dispatch; don't fan out. If exploration fails, proceed as greenfield and note the limitation.
Step 2 — Interview loop (one question at a time)
Track clarity qualitatively across a few dimensions — no numeric scoring:
| Dimension | Clear once it can be stated as… |
|---|---|
| Goal | the core outcome in one sentence — the key noun and what happens to it |
| Constraints | the boundaries, environment, and explicit non-goals |
| Success | how to verify it's done — concrete, testable acceptance |
| Context (brownfield only) | how it fits the existing code without breaking it |
Each round:
- Target the weakest dimension. Name it in one line first: "Goal is clear; constraints are still fuzzy → next question targets constraints."
- Ask exactly ONE question via
AskUserQuestion, with concrete options plus free-text. Aim it to expose an assumption, not to collect a feature list. (Brownfield: cite the file/symbol that prompted the question — "I found JWT auth insrc/auth/; extend it or diverge?") - Fold the answer in and re-judge that dimension.
When the idea is nearly clear, take one simplifier pass: "What's the simplest version that's still valuable?" / "Is <constraint> a real requirement or an assumption?" Then move to the spec.
Stop the loop when every applicable dimension is clear enough to write testable acceptance criteria, OR the user says "enough / let's go / build it" (allow after ~2 rounds). On early exit, name in one line what's still fuzzy so the gap is on record.
Soft cap: if the loop reaches ~8 rounds without converging, summarize what's clear, flag what isn't, and ask whether to proceed or keep going. Don't loop forever.
Step 3 — Approaches (only when there's a real fork)
If the idea has a genuine design fork (e.g. native app vs PWA, polling vs webhook), present 2–3 approaches with trade-offs and a recommendation in one message, and let the user pick. Skip this entirely when the idea is a requirement to clarify rather than a design to choose.
Do NOT produce a task breakdown here — decomposition into ## Task N: blocks is hyper-plan's job. The spec states what, not the task list.
Step 4 — Write the spec
-
Derive the slug from the idea, same rule as
hyper-plan/hyper-research: lowercase, ASCII only, alphanumerics + hyphen, first 5 words of the idea joined by-. Example: "Add OAuth login to the API" →add-oauth-login-to-the.- No-ASCII fallback (e.g. an all-Korean idea): the filename is the timestamp only (
<timestamp>.md), and the frontmatterslug:line is the bare key with an empty value:slug:(key, colon, single space, nothing after — NOTslug: "").
- No-ASCII fallback (e.g. an all-Korean idea): the filename is the timestamp only (
-
Resolve the path:
mkdir -p .hyperclaude/specs date -u +%Y%m%d-%H%MBase path
.hyperclaude/specs/<timestamp>-<slug>.md; if it exists, append-2,-3, … until free. -
Write the spec with the Write tool. Author NO
plugin-versionline — the PostToolUse stamp hook adds it post-write. Frontmatter keys, in this order:--- mode: interview idea: |- <idea, each line 2-space indented> slug: <slug> generated: <ISO-8601 timestamp> type: greenfield|brownfield --- # Spec: <title> ## Goal <one crisp paragraph — the core outcome, covering the whole idea> ## Constraints - <constraint> ## Non-Goals - <explicitly excluded scope> ## Acceptance Criteria - [ ] <testable criterion> ## Assumptions Resolved | Assumption | Resolution | |---|---| | <what was assumed / surfaced> | <what was decided> | ## Context <brownfield: the cited code findings (paths/symbols) this builds on or diverges from. greenfield: technology choices and constraints. Omit this section if empty.>Scale each section to the idea — a small idea gets a few lines per section, not padding. The spec captures the interview's conclusions, not its transcript.
Step 5 — User review + handoff
-
Tell the user the spec path and ask them to review it. Wait for approval (the HARD-GATE). If they request changes, revise the spec at the same path and re-confirm.
-
On approval, hand off — do NOT implement here. Pass the ORIGINAL idea text as the task argument — verbatim, the same text recorded in the spec's
idea:frontmatter — NOT the reworded Goal. This is what keeps the slug aligned:hyper-plan-loop/hyper-plan/hyper-researchderive their slug from$ARGUMENTSwith the same rule used in Step 4, so the same idea text yields the same slug and theresearch → plan → plan-reviewtrace stays linked. A reworded Goal would derive a different slug and silently break the trace. (The planning skills do not readspecs/— the slug match is what links them, plus the spec content you already hold in context.)- Straight to planning →
/hyperclaude:hyper-plan-loop <original idea>(plan ↔ review until clean;/hyperclaude:hyper-planwhen the user wants round-by-round control). For an oversized spec (beyond ~10–12 tasks, or several independent milestones) →/hyperclaude:hyper-plan <original idea>instead: the loop always produces one detailed plan, whilehyper-plansplits an oversized task into an epic roadmap. Either way, the spec's resolved requirements (Goal / Constraints / Acceptance Criteria) are already in this conversation from Step 4 — feed them to the planner as context. - Research first (when prior-art / pitfalls matter) →
/hyperclaude:hyper-research <original idea>, then the planning skill chosen above.
Default recommendation:
hyper-plan-loop(hyper-planfor an oversized spec); prependhyper-researchwhen the approach has real unknowns. - Straight to planning →
Anti-patterns
- Calling Codex / the bridge. This gate is Claude-only; review is downstream (
hyper-plan-review,hyper-code-review). - Batching questions. One per round; multiple at once produces shallow answers and blurs which dimension is being improved.
- Asking what the code already tells you. Explore first (brownfield) and cite the evidence in the question.
- Decomposing into tasks. That's
hyper-plan. The spec states what to build and how success is verified — not the ordered task list. - Implementing before spec approval. The HARD-GATE is absolute regardless of perceived simplicity.
- Hand-authoring a
<spec>-v2.mdsibling. In-session revisions overwrite the Step-4 path in place (Step 5); a separate re-run getting a new timestamped path is expected, not something to encode by hand.
Files in this skill
1hyper-interview skill questions
How do I install the hyper-interview skill in Claude Code?
Run npx degit zeikar/hyperclaude/skills/hyper-interview ~/.claude/skills/hyper-interview. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the hyper-interview skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is the purpose of the hyper-interview skill?
It acts as a requirements-clarification gate that turns vague or under-specified ideas into clear specifications through a one-question-at-a-time interview.
When should I use hyper-interview instead of hyper-plan?
Use hyper-interview when an idea is vague or under-specified. Use hyper-plan when the task is already clear and needs to be decomposed into specific tasks.
Where are the generated specifications stored?
The skill writes the completed specification to the .hyperclaude/specs/ directory using a timestamped markdown file.
Will the agent start writing code immediately after the interview?
No, there is a strict rule against writing code or scaffolding until the user has reviewed and approved the generated specification.