Agent skill

Ask User

You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous.

MITAuto-check passed

Install Ask User

skills CLI

$ npx skills add edlsh/pi-ask-user --skill ask-user -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install edlsh/pi-ask-user ask-user --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/edlsh/pi-ask-user.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/ask-user .claude/skills/ask-user && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "ask-user" agent skill from https://github.com/edlsh/pi-ask-user/tree/main/skills/ask-user into .claude/skills/ask-user/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "ask-user", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/edlsh/pi-ask-user/tree/main/skills/ask-user

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add edlsh/pi-ask-user --skill ask-user -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install edlsh/pi-ask-user ask-user --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/edlsh/pi-ask-user.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/ask-user .agents/skills/ask-user && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "ask-user" agent skill from https://github.com/edlsh/pi-ask-user/tree/main/skills/ask-user into .agents/skills/ask-user/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "ask-user", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add edlsh/pi-ask-user --skill ask-user -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install edlsh/pi-ask-user ask-user --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/edlsh/pi-ask-user.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/ask-user .cursor/skills/ask-user && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "ask-user" agent skill from https://github.com/edlsh/pi-ask-user/tree/main/skills/ask-user into .cursor/skills/ask-user/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "ask-user", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/edlsh/pi-ask-user.git --path skills/ask-user

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add edlsh/pi-ask-user --skill ask-user -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install edlsh/pi-ask-user ask-user --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/edlsh/pi-ask-user.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/ask-user .gemini/skills/ask-user && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "ask-user" agent skill from https://github.com/edlsh/pi-ask-user/tree/main/skills/ask-user into .gemini/skills/ask-user/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "ask-user", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install edlsh/pi-ask-user ask-user

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add edlsh/pi-ask-user --skill ask-user -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/edlsh/pi-ask-user.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/ask-user .github/skills/ask-user && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "ask-user" agent skill from https://github.com/edlsh/pi-ask-user/tree/main/skills/ask-user into .github/skills/ask-user/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "ask-user", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add edlsh/pi-ask-user --skill ask-user -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install edlsh/pi-ask-user ask-user --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/edlsh/pi-ask-user.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/ask-user .opencode/skills/ask-user && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "ask-user" agent skill from https://github.com/edlsh/pi-ask-user/tree/main/skills/ask-user into .opencode/skills/ask-user/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "ask-user", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: ask-user
GitHub stars: 169
Token cost: ~1.9k tokens
SKILL.md length: 739 words
Files: 2 (incl. references)
Skills in repo: 1
Repo updated: Oct 4, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous.

Works in 6 steps: Detect boundary → Gather evidence first → Synthesize context → …
SKILL.md covers Non-negotiable rule, Agent Protocol Handshake…, Anti-overasking guardrails… and ask_user payload quality…, plus 4 more sections
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Ask User is an agent skill from edlsh/pi-ask-user. You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous. Runs a decision handshake with the askuser tool: summarize context, present structured options, collect explicit user choice, then proceed.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including reference files (for example `references/ask-user-skill-extension-spec.md`).

It works with TypeScript. The repository describes itself as: Interactive decision-gating extension for pi — lets AI agents ask users questions with multiple-choice and freeform answers. The licence is MIT.

Example prompts

“/ask-user”

Workflow steps

6 steps, taken from the step headings in SKILL.md.

Detect boundary
Gather evidence first
Synthesize context
Ask one focused question
Commit the decision
Re-open only on new ambiguity

What it can do on your machine

Read from SKILL.md and the folder at commit e8b59a5. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are json).
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Ask User loads about 1.9k tokens when it runs, and up to ~2.9k if it reads all its reference files. Until then it costs about 67 tokens; SKILL.md has 739 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~67
When it runs · the whole SKILL.md, loaded when a task matches: ~1.9k
With references · SKILL.md plus every file in references/, read only if the agent opens them: ~2.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from edlsh/pi-ask-user at commit e8b59a5, republished under its MIT licence (© edlsh). 739 words, ~1,873 tokens.

Download SKILL.mdSave it as .claude/skills/ask-user/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.

name: ask-user
description: You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous. Runs a decision handshake with the ask_user tool: summarize context, present structured options, collect explicit user choice, then proceed.
metadata.short-description: Decision gate for ambiguity and high-stakes choices

Ask User Decision Gate

Use this skill to force explicit user alignment before consequential decisions.

This skill is about decision control, not general chit-chat.

Non-negotiable rule

Invoke ask_user before proceeding when any of the following is true:

The next step changes architecture, schema, API contracts, deployment strategy, or security posture.
The work is costly to undo (large refactor, migration, destructive edit, production-facing behavior change).
Requirements, constraints, or success criteria are unclear, conflicting, or missing.
Multiple valid options exist and the trade-off is preference-dependent.
You are about to assume something that can materially change implementation.

Do not skip this gate unless the user has already provided a clear, explicit decision for the exact trade-off.

Agent Protocol Handshake (required)

Follow this handshake in order.

1) Detect boundary

Classify the current step as:

high_stakes
ambiguous
both
clear (no gate needed)

If classification is not clear, continue.

2) Gather evidence first

Before asking, gather context from available tools (read, bash, exa, ref, etc.). Do not ask the user to decide blind.

3) Synthesize context

Prepare a short neutral summary (3-7 bullets or short paragraph) covering:

current state
key constraints
trade-offs
recommendation (if any)

4) Ask one focused question

Call ask_user with one decision at a time:

question: concrete decision prompt
context: synthesized summary
options: 2-5 clear choices when possible
allowMultiple: false unless independent selections are genuinely needed
allowFreeform: usually true
displayMode (optional): "overlay" (default) or "inline". Use "inline" when preceding assistant context (summary, trade-offs, recommendation) is essential to the decision and should remain visible — overlays cover the conversation underneath. The user may set a personal default via the PI_ASK_USER_DISPLAY_MODE environment variable; only pass this when you intentionally want to override it for one call.
contextExpanded (optional): true opens oversized context fully expanded instead of collapsed behind a one-line summary. The user may set a personal default via PI_ASK_USER_CONTEXT_EXPANDED; only pass this when the context is the evidence the user needs to weigh the options.

When 2-4 decisions at the same boundary are independent of each other and their prerequisites are settled, you may ask them together with questions instead of question. Each entry carries its own question, context, options, allowMultiple, and allowFreeform. Never batch a decision whose options depend on another answer; ask it in a later call once that answer is known.

5) Commit the decision

After response:

restate the decision in plain language
state what will be done next
proceed with implementation

6) Re-open only on new ambiguity

Ask again only if materially new uncertainty appears. Avoid repetitive confirmation loops.

Show full SKILL.md (316 more words)Show less

Anti-overasking guardrails (required)

Apply a strict question budget per decision boundary:

Max 1 ask_user call per decision boundary in normal cases.
Max 2 ask_user calls for the same boundary when first response is unclear/cancelled.
Never ask the same trade-off again without new evidence.

Escalation ladder:

Attempt 1: structured options + concise context.
Attempt 2 (only if needed): narrower question with agent recommendation and explicit choices:
- Proceed with recommended option
- Choose another option (freeform)
- Stop for now

After attempt 2:

If boundary is high_stakes or both: stop and mark blocked. Do not keep asking.
If boundary is ambiguous only and user says “your call” or equivalent: proceed with the most reversible default and state assumptions explicitly.

`ask_user` payload quality standard

Question quality

Use:

“Which option should we adopt for X?”
“Do you want A (fast) or B (safer) for Y?”

Avoid:

broad/open prompts with no decision boundary
multiple unrelated decisions in one question
questions that should be answered by reading code/docs first

Option quality

Options must be:

mutually understandable
short and outcome-oriented
explicit on trade-offs

Good options include a short description when trade-offs are non-obvious.

Recommended patterns

Single-select architecture decision

json

{
  "question": "Which caching strategy should we use for the first release?",
  "context": "Current API has p95 latency issues. Redis is fastest but adds infra complexity; in-memory cache is simpler but not shared across instances.",
  "options": [
    { "title": "In-memory cache", "description": "Simpler rollout, weaker horizontal consistency" },
    { "title": "Redis cache", "description": "Better consistency and scalability, more ops overhead" }
  ],
  "allowMultiple": false,
  "allowFreeform": true
}

Multi-select when decisions are independent

json

{
  "question": "Select the first-wave hardening items to implement now.",
  "context": "We can ship quickly with baseline controls, then add targeted hardening. Budget is limited to 1-2 days.",
  "options": [
    { "title": "Rate limiting" },
    { "title": "Audit logging" },
    { "title": "Input schema validation" },
    { "title": "Secrets rotation" }
  ],
  "allowMultiple": true,
  "allowFreeform": true
}

Independent decisions at one checkpoint

json

{
  "questions": [
    {
      "question": "Which logging backend should the service use?",
      "context": "Both integrate with the existing middleware; only the hosted option needs a new vendor contract.",
      "options": [
        { "title": "Self-hosted Loki", "description": "No new vendor, more ops work" },
        { "title": "Hosted Datadog", "description": "Fastest setup, recurring cost" }
      ]
    },
    {
      "question": "Should the first release include the admin dashboard?",
      "options": [{ "title": "Include it" }, { "title": "Defer it" }],
      "allowFreeform": false
    }
  ]
}

Anti-patterns

Asking ask_user without first gathering context
Using it for trivial formatting choices
Forcing options when freeform is clearly better
Asking the same question repeatedly without new information
Batching dependent decisions in questions, or using a batch to dodge the one-decision-per-question rule
Proceeding with high-stakes implementation after unclear/cancelled answer

If user cancels or answer is unclear

Pause execution and explain what is blocked. Use at most one narrower follow-up ask_user question (attempt 2). After that, do not continue asking in a loop:

for high-stakes decisions: remain blocked until explicit decision
for ambiguity-only decisions: proceed only if user delegated the choice ("your call")

Additional reference

For full trigger matrix, UX conventions, and extension interaction details, read:

references/ask-user-skill-extension-spec.md

Files

SKILL.md and 1 other file (references) in skills/ask-user of edlsh/pi-ask-user.

SKILL.md
references/ask-user-skill-extension-spec.md

Open the folder on GitHubat commit e8b59a5

Compare with similar skills

Ask User next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Ask User compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Ask User this skilledlsh/pi-ask-user	169	—	~1.9k	Automated safety check: Pass	MIT	5 days ago
MCP Server Builderanthropics/skills	180k	63 repos	~2.3k	Automated safety check: Pass	Apache-2.0	today
Web Artifacts Builderanthropics/skills	180k	40 repos	~769	Automated safety check: Pass	Apache-2.0	today
Typescript Advanced Typesrolling-scopes/rsschool-app	10k	25 repos	~4.2k	Automated safety check: Pass	MPL-2.0	6 days ago
Code Review ChecklistshareAI-lab/learn-claude-code	78k	4 repos	~1.1k	Automated safety check: Pass	MIT	12 days ago
MCP Server BuildershareAI-lab/learn-claude-code	78k	4 repos	~1.2k	Automated safety check: Pass	MIT	12 days ago

Similar skills

MCP Server Builder
anthropics/skills
Official
Guides the design and implementation of Model Context Protocol servers in TypeScript or Python, from tool naming and error messages to evaluation.
180k GitHub starsUsed in 63 repos~2.3k tokens
Agent WorkflowsAuto-check passed
Web Artifacts Builder
anthropics/skills
Official
Builds multi-component claude.ai HTML artifacts as a small React, TypeScript and Tailwind project, then bundles it into one shareable HTML file.
180k GitHub starsUsed in 40 repos~769 tokens
Frontend & DesignAuto-check passed
Typescript Advanced Types
rolling-scopes/rsschool-app
Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications.
10k GitHub starsUsed in 25 repos~4.2k tokens
DevelopmentAuto-check passed
Code Review Checklist
shareAI-lab/learn-claude-code
Reviews code against a five-part checklist covering security, correctness, performance, maintainability and testing, and reports findings in a fixed format.
78k GitHub starsUsed in 4 repos~1.1k tokens
DevelopmentAuto-check passed
MCP Server Builder
shareAI-lab/learn-claude-code
Walks through building MCP servers in Python or TypeScript that expose tools, resources and prompts to Claude, with templates, registration and testing.
78k GitHub starsUsed in 4 repos~1.2k tokens
Agent WorkflowsAuto-check passed
Nx Import
nrwl/nx
Import, merge, or combine repositories into an Nx workspace using nx import.
29k GitHub starsUsed in 6 repos~3.5k tokens
DevelopmentAuto-check passed

Works with

TypeScript

Questions about Ask User

What does Ask User do?

You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous. Ask User is an agent skill from edlsh/pi-ask-user. You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous.

How do I install Ask User in Claude Code?

Run `npx skills add edlsh/pi-ask-user --skill ask-user -a claude-code`. Or copy the skill folder (skills/ask-user in edlsh/pi-ask-user) into .claude/skills/ask-user in your project. Claude Code loads it when a task matches its description.

How do I install Ask User in Codex?

Run `npx skills add edlsh/pi-ask-user --skill ask-user -a codex`. Or copy the skill folder (skills/ask-user in edlsh/pi-ask-user) into .agents/skills/ask-user in your project. Codex loads it when a task matches its description.

Can I use Ask User in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add edlsh/pi-ask-user --skill ask-user -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ask-user, .gemini/skills/ask-user, .github/skills/ask-user and .opencode/skills/ask-user in your project.

What does Ask User need to run?

SKILL.md names no scripts, command-line tools or credentials: Ask User is instructions for the agent only.

Does Ask User access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Ask User safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Ask User use?

Ask User is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Ask User use?

About 1.9k tokens (SKILL.md is roughly 7.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.1k tokens, read only when the agent opens those files.

What are the alternatives to Ask User?

Skills that share tags, products or a category with Ask User: MCP Server Builder (anthropics/skills, 180k stars), Web Artifacts Builder (anthropics/skills, 180k stars), Typescript Advanced Types (rolling-scopes/rsschool-app, 10k stars) and Code Review Checklist (shareAI-lab/learn-claude-code, 78k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Ask User?

edlsh (a GitHub user) maintains it in edlsh/pi-ask-user, which has 169 GitHub stars. The repository was last updated on October 4, 2026.

Source: edlsh/pi-ask-user on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Ask User

Facts

At a glance

What it does

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Ask User Decision Gate

Non-negotiable rule

Agent Protocol Handshake (required)

1) Detect boundary

2) Gather evidence first

3) Synthesize context

4) Ask one focused question

5) Commit the decision

6) Re-open only on new ambiguity

Anti-overasking guardrails (required)

ask_user payload quality standard

Question quality

Option quality

Recommended patterns

Single-select architecture decision

Multi-select when decisions are independent

Independent decisions at one checkpoint

Anti-patterns

If user cancels or answer is unclear

Additional reference

Files

Compare with similar skills

Similar skills

MCP Server Builder

Web Artifacts Builder

Typescript Advanced Types

Code Review Checklist

MCP Server Builder

Nx Import

Related

Questions about Ask User

`ask_user` payload quality standard