Some decisions you can't make alone. The facts sit in another person's head: a client, a domain expert, or a colleague on a team you don't sit with. to-questionnaire turns that gap into a questionnaire. A questionnaire is a Markdown document of questions you hand to one person. They fill it in when they have time, or you fill it in together in a meeting.
When to use it
Use it when a decision is blocked on knowledge that lives in one other person's head, such as an exec who owns the business rules.
You start it yourself, by name. The agent never starts it on its own.
When not to use it
If the answers are yours to give, use grill-me. It interviews you about the subject. to-questionnaire is its inverse: it interviews you only about the send, and the questions go to someone else.
If the facts are written down in official docs or source code, use research. It reads primary sources and leaves a cited Markdown file.
What it needs to start
Two things you can always answer, asked one at a time:
Who is it going to? Their role, what they know, and how they relate to you. This sets the tone, and how much background the document must give.
What do you need back? The decisions or facts you can't settle alone.
That's the Skill's rule: grill the send, not the subject. The questions in the document then aim at the gap between what the recipient knows and what you need.
Who is it going to?Their role, what they know, and how they relate to you.
What do you need back?The decisions or facts you can't settle alone.
Two things you can always answer, asked one at a time
to-questionnaire-<slug>.mdin the current folder
They fill it in when they have timeor you fill it in together in a meeting
material for the main Flowfor example a grill-with-docs session
grill the send, not the subject
What it creates
One file, to-questionnaire-<slug>.md, in the current folder. The slug is a short name from the topic, and the agent tells you the path. There's no Issue and no branch.
The document has a fixed shape:
why it exists, who it's from and to, and how the answers will be used;
a short paragraph of context, and how to answer: "I don't know" is a useful answer;
the questions, most important first, because you may only get one pass, grouped under headings by theme once there are more than a handful;
one idea per question, with space to answer right beneath it;
a closing "Anything else?".
What comes back is material for the main Flow, for example a grill-with-docs session.
Going deeper
5 min read · Going deeper not read
Why it exists
Matt's page on the Skill (updated 2026-08-24) names the usual moment: a grilling session "that stalls because some of the questions it raised aren't yours to answer." An interview about the subject can't help you then. The page says "not knowing the topic is why you're writing to someone else." In his v1.2 video (2026-08-05), Matt gives its purpose: "you take the decisions inside a grilling session and you pull them out into a document".
It began in Matt's in-progress bucket. The description of the pull request that added it (2026-07-14) said "The behaviour needs shaking out against a few real sends" first. Matt's v1.2 notes (for the release his 2026-08-05 video announces) say that it "graduates out of in-progress/ into the Productivity bucket."
Matt doesn't see it as permanent. In the same video he calls it "a skill that I hope someday to delete". He says it's a patch, because agents are still hard to work on together with other people.
How it works underneath
Matt sorts grill-me, grill-with-docs, to-questionnaire and prototype by one question: where are the answers? They can be in your own head, unsharpened, in the codebase, in someone else's head, or in nobody's head yet. His page says which one to reach for in each case, in that order.
Citations (47)
From snapshot/skills/to-questionnaire/SKILL.md, line 7: “Turn something the user can't 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.”
From snapshot/skills/ask-matt/SKILL.md, line 89: “It's the inverse of /grill-me: instead of interviewing you about the subject, it interviews you about the send (who it's going to, what you need back) and aims the questions at the gap.”
So it is not a batch mode of grill-me. Matt's page says grill-me already asks the whole frontier of open questions in rounds. The difference is "about whose head the answers are in, not how the questions are delivered."
The questions are a flat list, not a tree that skips a section because of an earlier answer. Grilling recomputes its next round from your answers. A branching document would have to plan every question ahead of every answer. Matt's page says a branching design was explored and did not ship, because a model "that plans more than two or three questions ahead of a real answer plans badly".
The document also asks for "I don't know". In Matt's words, "a vague answer and a confidently wrong one look identical once they're back in your context."
A real example
Matt built it for himself. In his v1.2 notes he says: "I built it during a /wayfinder session on a garden office". The agent was grilling him, "but the person to ask was my wife." She would use the room too, so they had to design it together.
In the video he tells the rest. He had the agent turn what it was going to ask into a Markdown document. He put that into a Google Doc, and they went through it together. Then they "pulled the answers back in to the agent".
Where it goes wrong
Matt's page answers the common questions:
Run in a fresh session, it knows nothing. It has no step that reads your grilling session. It works because you run it in the same conversation. In a fresh session, you must give the topic again yourself.
Several people hold the answers. One run makes one document for one person. If three people hold three parts, run it three times. A document that routes questions by role "did not ship".
You expect it to send the document. It doesn't. It writes the file and tells you the path. Delivery is yours: a Ticket, a Slack thread, an email, or a shared screen.
The page's "It's working if" list adds a warning. The Skill should ask about the recipient and what you need back, then stop. If it asks about the subject itself, "the skill has gone wrong". The list also gives a test for the answers. They should be "usable input for a new grilling round, rather than a fresh set of questions."
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), plan the class booking rules with grill-with-docs. Some questions will belong to the studio owner, not to you: how late someone can cancel, or what happens when a class is full. In that same conversation, run /to-questionnaire.
When it asks who it's going to, describe the studio owner: not technical, and the person who sets the rules.
When it asks what you need back, name the two or three rules you can't decide.
Check the file against Matt's test: every rule you named has a question, and someone who wasn't in the conversation would know why they got it and by when to reply.
Hand it to a friend to play the studio owner, then bring the answers back into the booking plan.
Going deeper's Check questions are asked in Next up.
“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.”
From snapshot/skills/to-questionnaire/SKILL.md, line 20: “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.”
From snapshot/web/aihero.dev/skills-to-questionnaire.md, lines 38–43: “| The answers are in… | Reach for | | --- | --- | | Your own head, unsharpened | grill-me | | The codebase | grill-with-docs | | Someone else's head | to-questionnaire | | Nobody's head yet, the question needs something to react to | prototype |”
From snapshot/web/youtube.com/watch-v-gaddrddczo4.md, lines 135–137: “And so I got the agent to take the stuff it was going to ask in the grilling session and turn it into a markdown document. [09:37] I then put that into a Google doc. [09:39] I sent that over to my wife and we walk through it together and then we pulled the answers back in to the agent.”
From snapshot/web/aihero.dev/skills-to-questionnaire.md, line 74: “If three people hold three parts of the answer, run it three times, once per person. People have asked for one document that routes questions by discipline or role, but that did not ship.”
From snapshot/skills/ask-matt/SKILL.md, line 85: “If you are in a working directory, use /grill-with-docs instead: it runs the same interview and leaves a paper trail, so it is strictly the better one.”
From snapshot/web/aihero.dev/skills-to-questionnaire.md, line 36: “Reach for it when a decision is blocked on knowledge that lives in one other person's head: a client, a domain expert, an exec who owns the business rules, a colleague on a team you don't sit with.”