Skip to main content
skill CX Codex

maestro-questionnaire — Claude Code skill: what it does

The maestro-questionnaire skill turns an unresolved decision into a Markdown questionnaire for someone with the missing knowledge. Use it to collect answers asynchronously or in a meeting.

MIT ★ 238 updated 2026-10-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ReinaMacCredy/maestro --skill maestro-questionnaire -a claude-code
Open on GitHub

What maestro-questionnaire does

The agent first asks who will receive the questionnaire and what facts or decisions the user needs from them. It then drafts questions around the gap between the recipient’s knowledge and the user’s needs. The document puts the most important questions first and includes context, answering guidance, and a space for each response.

With an active Maestro bundle, the questionnaire goes to .maestro/bundle/<bundle-id>/QUESTIONNAIRE-<slug>.md; the agent also records the wait in the work note and sets the bundle’s next action to receiving the answers. Without an active bundle, it writes questionnaire-<slug>.md in the current directory. The skill does not modify code.

Once answers arrive, the workflow records them as draft decisions and locks those decisions in Maestro. The active-bundle workflow uses work and bundle IDs, so have those available if you want its generated path and tracking commands.

What it helps with

  • Draft questions for a decision the user cannot settle alone
  • Ask a knowledge holder for facts needed to make a choice
  • Prepare a Markdown form for someone to complete before a meeting
  • Turn returned answers into recorded Maestro decisions

Example prompts for the agent

  • Create a questionnaire for the colleague who knows our launch requirements so I can choose the expected system load.
  • Draft questions for the client to answer before our meeting about the decisions I still need to make.
  • Write a questionnaire for the active bundle and set the next action to receiving the answers.

How to install maestro-questionnaire

1Skills CLI (Vercel)

npx skills add ReinaMacCredy/maestro --skill maestro-questionnaire -a claude-code

2Manually: put the files in place

~/.claude/skills/maestro-questionnaire/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/maestro-questionnaire/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about maestro-questionnaire

How do I install maestro-questionnaire in Claude Code?

Run npx skills add ReinaMacCredy/maestro --skill maestro-questionnaire -a claude-code. The installed skill file is at ~/.claude/skills/maestro-questionnaire/SKILL.md.

What does maestro-questionnaire do?

It asks who can provide the missing knowledge and what the user needs to learn, then drafts a Markdown questionnaire for that person.

Where does it save a questionnaire for an active Maestro bundle?

It writes to .maestro/bundle/<bundle-id>/QUESTIONNAIRE-<slug>.md, records the wait in a work note, and sets the bundle’s next action to receiving the answers.

Source text

SKILL.md · MIT
---
name: maestro-questionnaire
description: Turn a decision the user cannot fully answer into a Markdown questionnaire for the one person who can - filled in async, or together over a meeting. Also triggers on Vietnamese phrasings such as phỏng vấn đi, phỏng vấn tôi, interview tôi.
review-date: 2026-11-28
---
<!-- maestro-skill-version: dev -->
<!-- adapted from Matt Pocock's to-questionnaire -->

# maestro-questionnaire

Turn something the user cannot answer alone into a **questionnaire**: a
Markdown document they hand to one person to fill in async, or fill out
together over a meeting. The recipient holds knowledge the user lacks; the
questionnaire pulls it out of them. Read-only toward code; any tier may use it.

**Grill the send, not the subject.** Interview the user only about the
_send_, which they can always answer: who it goes to, and what they need
back. The questions in the document then target the **gap** between what the
recipient knows and what the user needs.

1. **Who is it going to?** Ask, in one exchange, the recipient's role,
   expertise, and relationship to the user. This fixes the questionnaire's
   tone and how much context it must carry. Done when you know who the
   recipient is and what they know that the user does not.

2. **What do you need back?** Ask, in one exchange, the specific decisions
   or facts the user cannot resolve alone and needs from this person. Done
   when you have a concrete list of what the user must walk away able to do
   or decide.

3. **Write the questionnaire.** Draft questions aimed at the gap from steps
   1 and 2, following the Document structure below. When an active bundle
   owns the decision, write it to
   `.maestro/bundle/<bundle-id>/QUESTIONNAIRE-<slug>.md`, record the wait as
   `maestro work note <id> "blocked: questionnaire <slug> sent to <role>"`,
   and set the bundle's NOTES.md Next Action to the return of the answers;
   otherwise write `questionnaire-<slug>.md` in the current directory. Report
   the path. Done when the file exists and every item the user named in step
   2 is covered by a question.

When the answers come back, they are settled forks: record each as
`maestro decision draft "<answer>" --rationale "<why, per <recipient>>" --work <id>`
then `maestro decision lock <id>`, and clear the Next Action. The filled
questionnaire is the evidence the decision cites.

## Document structure

Frame the document as a **discovery questionnaire**: the user lacks context,
the recipient holds it. Order questions most-important-first, since async
means you may only get one pass, and group them under `##` headings by theme
once there are more than a handful. Write it using the template below.

<questionnaire-template>

# <Questionnaire title>

**Purpose:** why this questionnaire exists and the decision riding on it.

**From:** <the user> **To:** <the recipient> **How your answers will be
used:** <where they go>

## Context

One paragraph orienting a recipient who was not in the user's head. Enough to
answer well, not a page.

## How to answer

Deadline and rough effort. Partial answers and "I don't know" are useful;
flag anything you are unsure of rather than skipping it.

## <Theme heading>

One `##` section per theme. Under each, its questions, most-important-first.
Every question is one idea, never compound, with an answer stub directly
beneath, and a one-line _why this matters_ only where the question could be
misread or invite a throwaway answer.

<question-example>
### What load is the system expected to handle at launch?

_Why this matters: it decides whether we provision for burst traffic now or
defer it._

>
</question-example>

## Anything else?

A closing catch-all: anything we did not ask that we should know?

</questionnaire-template>

© ReinaMacCredy · MIT · ReinaMacCredy/maestro

Similar skills

SKILL.md skills catalog →
to-questionnaire Matt Pocock to-questionnaire turns a decision you cannot answer alone into a Markdown questionnaire for someone with the missing context. Use it to collect answers asynchronously or work through questions in a meeting. CX Codex +1 498,319installs sumsub-create-questionnaire sumsub sumsub-create-questionnaire turns a short spec into a Sumsub KYC questionnaire definition, pushes it to the API and hands back the id for level wiring. CX Codex +1 1,400installs claude-skill-app-onboarding-questionnaire reason-machines claude-skill-app-onboarding-questionnaire reads your app codebase and generates a questionnaire-style onboarding flow: copy, screen designs and working code in your framework. CX Codex +1 593installs maestro xenitV1 maestro turns the agent into a software architect: plan-act-verify loop, persistent project memory, and routing to domain sub-skills. CX Codex +1 604installs maestro-e2e raphaelbarbosaqwerty Helps your agent write and debug Maestro E2E tests: login, signup, navigation, permission dialogs. Covers iOS, Android, Flutter, React Native and web. CX Codex +1 543installs find-skills vercel-labs find-skills is a Claude Code skill that locates agent skills for a task and helps assess the results. It activates when someone asks for a capability that may already be installable. CX Codex +1 4,400,000installs frontend-design official anthropics The frontend-design skill guides intentional visual design for new interfaces and redesigns. Use it when a generic generated UI is not enough. CX Codex +1 1,025,790installs agent-browser vercel-labs This Claude Code skill automates browser interaction for tasks like navigating sites, filling forms, and testing web apps. It also supports exploratory QA and Electron app automation. CX Codex +1 1,600,000installs

From the same set10

The whole set →
verify-maestro verify-maestro verifies Maestro repository changes in an isolated scratch HOME, runs realistic CLI user journeys, and writes an execution log with exit codes. CX Codex +1 ★ 238repo stars maestro-coach maestro-coach — a skill for Claude and Codex that unjams a question you got stuck on and teaches the concept behind a decision using your own repo code. CX Codex +1 ★ 238repo stars maestro-bundle maestro-bundle manages SPEC, NOTES, and VERIFY bundle lifecycles and controls context handoffs across agent sessions in Maestro. CX Codex +1 ★ 238repo stars maestro-verify The maestro-verify skill checks acceptance criteria against verification evidence, records a verdict, and guides bundle closure. Use it before handing work back or closing a task. CX Codex +1 ★ 238repo stars maestro-design maestro-design — a skill that resolves blocking unknowns before implementation: architecture choice, modeling, prototyping, and recording durable decisions. CX Codex +1 ★ 238repo stars maestro-graph maestro-graph — a skill for Claude Code and Codex that runs a task along a predefined graph: spawns agents on each node, collects results, and moves to the next step. CX Codex +1 ★ 238repo stars maestro-work maestro-work is a Claude Code skill that defines shared playbook rules for task briefs, work handbacks, and records. It applies when an agent delegates work or tracks a task in Maestro. CX Codex +1 ★ 238repo stars maestro-council maestro-council runs a structured council over a call you cannot cheaply undo: sealed seats, a premise check, cross-examination and one binding verdict. CX Codex +1 ★ 238repo stars

Project sponsors

Companies that keep this analytics open