Guide · Agent skill
How to use the Asking User Questions agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Asking User Questions skill is a shared rulebook that tells an AI agent how to ask you questions through an ask_user_question tool. It does not run a task on its own. Instead, it shapes how the agent groups open decisions into rounds, which questions it asks, and how it presents options. This guide explains what the skill changes, how to install it, how to trigger it, and what to check before relying on it.
Asking User QuestionsJetBrains/thinkrail · Apache-2.0 Download the skill Quick start
- 1Download and unzip. Download the ZIP from this page and unzip it to get the asking-user-questions folder containing SKILL.md.
- 2Place the folder. Move the folder to ~/.claude/skills/ for personal use or to a project's .claude/skills/ folder for one project.
- 3Or upload in the apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill instead.
- 4Check the host tool. Confirm your host agent has an ask_user_question tool; without it the skill uses plain chat questions.
- 5Run a workflow. Start a thinkrail workflow skill that reaches a question step, or ask for a decision-heavy change.
- 6Answer the round. Answer the questions in the card, choose options, or skip; skipped questions are recorded as unconfirmed.
What the skill makes the agent do
When a workflow reaches a step where a decision is needed, the agent uses this skill to decide how to ask. It collects the open decisions whose prerequisites are already settled into one round, and asks only the ones whose answers would change the outcome. Facts that the workspace, specs, or web can answer are looked up rather than asked.
The skill also covers what happens when things go wrong. If you skip a question, the agent settles it on its recommended answer and records it as unconfirmed. If the ask_user_question tool is not available, the agent asks the same questions as a plain chat message and waits for your reply.
- Asks in rounds, and only questions that do not depend on each other unanswered.
- Looks up facts itself instead of asking you for them.
- Puts a recommended option first, labelled (Recommended), with a one-line reason.
- Stops interviewing you when the open decisions are exhausted, with no extra "are we aligned?" round.
Install the skill from a ZIP file
Download the ZIP from this page and unzip it. The package contains a single file, SKILL.md. Put the unzipped skill folder in one of two places, depending on how you want to use it.
For a personal setup available across projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/asking-user-questions/
- Project only: .claude/skills/asking-user-questions/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the skill
Trigger the skill with natural requests
You do not need a special command. The skill is meant to be used by workflow skills from the thinkrail family, which name it at the steps where they ask questions. You can also ask for it directly in a request that involves a decision, such as a feature with several possible behaviours.
The skill's own description says it applies when composing an ask_user_question round inside a workflow, or when a workflow skill names it at a question step. It is not a workflow itself, so it will not start work by itself.
- Ask the agent to interview you in rounds before writing a spec for a new feature.
- Request clarifying questions before changes to behaviour that existing users depend on.
- Run a thinkrail workflow skill that reaches a question step.
Examples of good questions
The skill asks for concrete scenarios rather than abstract principles. A question should name the actual feature, screen, or file and show a real situation. Options are framed as behaviour the user can see, not as implementation details.
For example, instead of asking how concurrency should be handled, the agent asks what should happen when a file is dragged onto a busy session: queue it or reject it. Each option describes the consequence for the user.
- Good: "A user drags a file onto a busy session. Queue it or reject it?"
- Avoid: "How should concurrency be handled?"
- Good option: "Collapsing a project stays collapsed after a rename"
What you need before using it
The skill depends on two things. The host agent needs an ask_user_question tool. Without it, the skill falls back to plain chat questions and offers less structure. The skill is also described as shared norms for the referencing thinkrail workflow skills, so on its own it has no task to run.
The skill has no scripts and makes no network calls, according to its package description.
- An ask_user_question tool in the host agent (otherwise plain chat questions are used).
- The referencing thinkrail workflow skills, since this file is written as shared norms for them.
- No scripts are run and no network use is declared.
Safety notes and tips
Because the skill runs no scripts and uses no network, its main effect is on how questions are asked and recorded. Check the workflow's artifact to see which answers were confirmed and which were assumed. Assumptions made after a skipped question are marked unconfirmed.
If you find that answers keep coming back as "I don't know", the skill treats this as a sign the question was framed in technical terms. The agent should re-explain in plain language about visible behaviour.
- Review recorded assumptions in the workflow artifact after a skipped round.
- If the agent asks a question you feel it could have looked up, say so, since looking up facts is the intended behaviour.
- A composer message sent while a question card is open replaces the round; re-check any open questions afterward.
What people use it for
- Clarifying scope and edge cases before a developer writes a spec for a multi-step agent workflow.
- Confirming an inferred requirement with a yes/adjust question instead of an open-ended one.
- Reducing assumptions in a team that uses the thinkrail workflow family on shared features.
- Asking fewer but sharper questions before an agent changes existing behaviour that must migrate.
Frequently asked questions
Is the Asking User Questions skill free?
The skill is published under the Apache-2.0 licence, as stated on this page. Check the licence file in the source repository for the full terms.
What do I need to use the Asking User Questions skill?
You need a host agent with an ask_user_question tool. The skill is also written as shared norms for the thinkrail workflow skills that reference it, so it is not meant to run alone.
Does this skill run scripts or access the internet?
No. The package has no scripts and does not declare network use. It only shapes how the agent asks questions.
How do I install the Asking User Questions skill?
Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ or in a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
What happens if my agent does not have ask_user_question?
The skill falls back to asking the same round as a plain chat message, with numbered options and the recommended one first. The agent then waits for your reply.
Is this skill an alternative to a workflow skill?
No. It is a set of guidelines used by other workflow skills. If you want an agent to perform a complete task, you need a workflow skill that references it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers and teams using thinkrail-style spec-driven workflows who want consistent, targeted clarifying questions. It is not useful for simple one-off tasks, since the skill itself says zero rounds is correct when no decisions need input. If you need an agent to produce files or perform an action on its own, or your host has no ask_user_question tool, choose a different skill.
Download the skill