Menu
This skill should be used when the user provides a vague request, asks to clarify requirements, structure a task, or refine a prompt for multi-agent orchestration.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Search prior session history to recall how similar work was handled before. Use when you want to leverage a past approach, check prior experience on a topic, answer "how was this handled before", or cross-verify current handling against precedent from earlier sessions.
This skill should be used when looking up which agents own or consume specific skills, understanding skill-agent relationships, or routing tasks based on skill ownership.
This skill should be used when handling verification steps, quality gates, pre-commit checks, test failures, lint errors, build verification, or mandatory validation before task completion.
This skill should be used when handling agent model selection, tool access permissions, behavioral guardrails, MCP tool preferences, or any question about what agents can/cannot do.
Turn any codebase into a beautiful, interactive single-page HTML course that teaches how the code works to non-technical people. Use this skill whenever someone wants to create an interactive course, tutorial, or educational walkthrough from a codebase or project. Also trigger when users mention 'turn this into a course,' 'explain this codebase interactively,' 'teach this code,' 'interactive tutorial from code,' 'codebase walkthrough,' 'learn from this codebase,' or 'make a course from this project.' This skill produces a stunning, self-contained HTML file with scroll-based navigation, animated visualizations, embedded quizzes, and code-with-plain-English side-by-side translations.
This skill should be used when classifying tasks, routing to agents, determining complexity, or handling task routing, agent selection, verification requirements, and multi-component changes.
| name | prompt-refinement |
| description | This skill should be used when the user provides a vague request, asks to clarify requirements, structure a task, or refine a prompt for multi-agent orchestration. |
Prompt refinement transforms ambiguous or incomplete user requests into clear, structured task specifications suitable for multi-agent orchestration. This skill bridges natural language input and the precise specifications required by downstream agents.
Ensure tasks entering the orchestration pipeline have:
Apply prompt refinement when:
/orchestrate or /plan commands**Goal**: <one-sentence objective stating what will be accomplished>
**Description**: <2-3 sentences providing context and scope>
**Actions**:
1. <specific, atomic action with clear target>
2. <specific, atomic action with clear target>
3. ...
**Constraints**: <what must not be broken, changed, or violated>
**Assumptions**: <what is taken for granted — surfaces risks early>
| Field | Requirements | Example |
|---|---|---|
| Goal | Single sentence, verb-first, specific outcome | "Implement rate limiting on /api/users endpoint" |
| Description | Context, scope boundaries | "Add rate limiting to prevent API abuse. Limit to 100 req/min per IP." |
| Actions | Numbered, ordered, atomic steps | "1. Explore existing middleware patterns" |
| Constraints | Non-negotiable requirements; what must stay intact | "Must not alter existing auth cookie format" |
| Assumptions | Preconditions taken for granted | "Redis is already provisioned" |
After capturing all five fields, the orchestrator classifies task_complexity (trivial/exploratory/implementation/complex/research) and persists the structured intent to the state file via --set-intent-goal, --set-intent-description, --set-intent-actions, --set-intent-constraints, --set-intent-assumptions, and --set-task-complexity. These values are passed verbatim (no re-summarization) to all downstream agents.
A prompt likely needs clarification if:
| Signal | Example | Issue |
|---|---|---|
| Missing scope | "fix the bug" | Which bug? Where? |
| Vague outcome | "make it better" | Better how? |
| Multiple meanings | "update the API" | Which endpoint? What change? |
| Implicit assumptions | "deploy it" | Where? How? |
For detailed ambiguity detection, see references/ambiguity-detection.md.
Before I proceed, I need to clarify:
<single focused question>
Options:
A) <most likely option>
B) <second most likely>
C) <third option if applicable>
D) Something else (please specify)
| Rule | Rationale |
|---|---|
| Single question | Reduces cognitive load |
| Concrete options | Speeds up response |
| Max two rounds | Avoids frustration |
| Include escape hatch | Prevents forced incorrect choice |
Always Clarify:
Safe to Assume:
For detailed clarification strategies, see references/clarification-strategies.md.
| Category | Example |
|---|---|
| Multi-file changes | "Add authentication to all routes" |
| Feature implementations | "Implement dark mode" |
| Bug investigation | "Fix the login issue" |
| Refactoring | "Refactor user service" |
| Integration | "Integrate Stripe" |
| Category | Example |
|---|---|
| Questions | "What does this function do?" |
| Single-file edits | "Add comment to line 42" |
| Git operations | "Commit these changes" |
| Documentation lookups | "Show API endpoints" |
Is it a question about existing code? -> Pass through
Does it require code changes? -> If no, pass through
Is target explicit AND single file? -> Pass through
Otherwise -> Refine for orchestration
For detailed orchestration detection, see references/orchestration-detection.md.
Is it orchestration-related?
├── NO -> Pass through unchanged
└── YES -> Continue to Step 2
Check ambiguity signals
├── High ambiguity -> Go to Step 3 (Clarify)
└── Low ambiguity -> Go to Step 4 (Refine)
| Score | Action |
|---|---|
| 0-2 | Proceed with refinement |
| 3-4 | State assumption and proceed |
| 5+ | Ask clarifying question |
Short imperative with a concrete target → state assumption and proceed, do not ask.
| Prompt Type | Action |
|---|---|
| Clear + orchestration | Refine to template |
| Ambiguous + orchestration | Clarify then refine |
| Clear + non-orchestration | Pass through |
| Ambiguous + non-orchestration | Minimal clarification |