agentleFS
doivamongdoivamong/agent-workbench/.claude/skills/prompt-refiner/SKILL.md

prompt-refiner

Skill2 starsChanged 6 months agoMITView on GitHub

WHAT: turn a vague, multi-part request into a crisp, executable one before doing any work — clarify intent, surface hidden assumptions, restate the scope. USE WHEN: a request is long but underspecified (no files, no acceptance criteria, several intents at once). The UserPromptSubmit hook (prompt-refiner-inject.py) flags these automatically and asks you to run this first. DO NOT TRIGGER: the request is already specific (file paths, clear outcome); it's a trivial one-liner; or the user prefixed it to bypass refinement.

9 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

Prompt refiner

Announce on activation: "Using prompt-refiner — I'll confirm scope before executing."

The cheapest place to fix a misunderstanding is before the work starts. This skill is a 30-second gate, not a ceremony.

Process

  1. Classify intent. Is this a fix, a feature, a review, research, or a question? If two or more at once, that's a sign the request needs splitting.
  2. Spot the ambiguity — and don't trust the premises. What's missing that changes what you'd build — scope, target files, expected output, constraints, the definition of done? If the request asserts "X already does Y" or names a file, grep/read to verify the claim first — a confident wrong premise is the most expensive ambiguity. Scan the requirement-level dimensions too — data shape, terminology consistency, and whether the acceptance check is actually testable — and when several are unclear, surface the highest impact × uncertainty one first.
  3. Decide the path by clarity (a 4-tier scale):
    • Crystal → restate it in one line and proceed (no friction).
    • One missing piece → ask exactly one focused question, then proceed.
    • Several intents / wide-open scope → propose a concrete interpretation (scope + acceptance criteria) and get a yes before building.
    • Claims-heavy or high-stakes → grill mode: interview one focused question at a time, verifying each load-bearing claim against the code, until the spec is airtight.
  4. Restate, don't expand. The rewrite must preserve the original intent — never quietly add scope the user didn't ask for. Shorter and sharper, not longer. An ambiguity you choose to proceed past becomes a stated assumption, never a silent default — surface it on the Assumptions line so a wrong guess is visible and correctable, not discovered after the build.

Output shape

Intent: <fix | feature | review | research | question>
Restated: <one sentence, the crisp version>
Acceptance: <observable check(s) that mean "done">
Open question (if any): <the single thing you need answered>
Assumptions (correct me): <what I'm taking as given to proceed — stated, not baked in silently>
Out of scope: <what this deliberately will NOT touch — names the boundary so creep is visible>
→ Proceed? (or the user corrects)

Anti-rationalization

You'll thinkReality
"I get the gist, I'll just start"The gist is where wrong assumptions hide. One sentence of restatement catches them — a 10-second question beats a 10-minute wrong build.
"I'll infer the missing scope"Inferring scope the user didn't state is how scope creep and rework begin. State it and confirm.
"The request says it works that way, so it does"Premises are claims, not facts. Grep before you build on one.
"They said 'sounds good', so we're aligned"A vague yes — "sounds good", "whatever you think", silence — confirms a vibe, not the scope. Alignment means they engaged the restate / acceptance / out-of-scope; if they didn't, the spec is still open — ask the one question that forces a real choice.

Note

This skill pairs with the UserPromptSubmit hook .claude/hooks/prompt-refiner-inject.py, which detects vague prompts and reminds the agent to run this skill. If you remove the skill, also update or remove that hook so it doesn't reference a skill that no longer exists.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.