Index of every page on this site: llms.txt
All skills
moizibnyousaf avatar

/ask-questions-if-underspecified

@6d95c78
Run it yourself

Clarify requirements before implementing. Do not use automatically, only when invoked explicitly.

Use this Skill: https://skilld.dev/gh/moizibnyousaf/ai-agent-skills/ask-questions-if-underspecified

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈33 tokens for metadata: the name and description. ≈901 when used: this file.

Description uses 1.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈131 characters, or 1.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Ask Questions If Underspecified

Goal

Ask the minimum set of clarifying questions needed to avoid wrong work; do not start implementing until the must-have questions are answered (or the user explicitly approves proceeding with stated assumptions).

Workflow

1) Decide whether the request is underspecified

Treat a request as underspecified if after exploring how to perform the work, some or all of the following are not clear:

  • Define the objective (what should change vs stay the same)
  • Define "done" (acceptance criteria, examples, edge cases)
  • Define scope (which files/components/users are in/out)
  • Define constraints (compatibility, performance, style, deps, time)
  • Identify environment (language/runtime versions, OS, build/test runner)
  • Clarify safety/reversibility (data migration, rollout/rollback, risk)

If multiple plausible interpretations exist, assume it is underspecified.

2) Ask must-have questions first (keep it small)

Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.

Make questions easy to answer:

  • Optimize for scannability (short, numbered questions; avoid paragraphs)
  • Offer multiple-choice options when possible
  • Suggest reasonable defaults when appropriate (mark them clearly as the default/recommended choice; bold the recommended choice in the list, or if you present options in a code block, put a bold "Recommended" line immediately above the block and also tag defaults inside the block)
  • Include a fast-path response (e.g., reply defaults to accept all recommended/default choices)
  • Include a low-friction "not sure" option when helpful (e.g., "Not sure - use default")
  • Separate "Need to know" from "Nice to know" if that reduces friction
  • Structure options so the user can respond with compact decisions (e.g., 1b 2a 3c); restate the chosen options in plain language to confirm

3) Pause before acting

Until must-have answers arrive:

  • Do not run commands, edit files, or produce a detailed plan that depends on unknowns
  • Do perform a clearly labeled, low-risk discovery step only if it does not commit you to a direction (e.g., inspect repo structure, read relevant config files)

If the user explicitly asks you to proceed without answers:

  • State your assumptions as a short numbered list
  • Ask for confirmation; proceed only after they confirm or correct them

4) Confirm interpretation, then proceed

Once you have answers, restate the requirements in 1-3 sentences (including key constraints and what success looks like), then start work.

Question templates

  • "Before I start, I need: (1) ..., (2) ..., (3) .... If you don't care about (2), I will assume ...."
  • "Which of these should it be? A) ... B) ... C) ... (pick one)"
  • "What would you consider 'done'? For example: ..."
  • "Any constraints I must follow (versions, performance, style, deps)? If none, I will target the existing project defaults."
  • Use numbered questions with lettered options and a clear reply format
1) Scope?
a) Minimal change (default)
b) Refactor while touching the area
c) Not sure - use default
2) Compatibility target?
a) Current project defaults (default)
b) Also support older versions: <specify>
c) Not sure - use default

Reply with: defaults (or 1a 2a)

Anti-patterns

  • Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
  • Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.

Originally created by @thsottiaux

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides instructions for the AI agent to clarify ambiguous user requests by asking targeted questions before proceeding with a task. It is purely instructional and does not contain any executable code, network requests, or sensitive file access.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

Signed by skilld at 6d95c78. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago
version
4.1.0

README badge

README badge for moizibnyousaf/ai-agent-skills/ask-questions-if-underspecified