How to Make Your SKILL.md Interactive

I've been recently playing with Matt Pocock's grill-me skill, which I found to be very useful. If you haven't checked it out yet, you definitely should.

The basic idea of grill-me is to help you come up with a plan by asking you a bunch of questions. The agent will do a round of questions and ask you about more and more details until it is able to create a comprehensive plan.

I've really enjoyed this, but there's a little detail which I felt like could be improved. When the skill asks you a question, it gives you a question number and a bunch of options. The way you interact with it is to respond to the agent with the number of the option or written response.

I thought it would be nice if instead of having the agent write down all of the questions and the options, you’d have an option picker. The same kind of back and forth that you usually get in Claude Code or Cursor or Codex when agent asks you for details.

Turns out there's an API for that, which you can reference in your SKILL.md file.

In Claude Code the tool is called AskUserQuestion. You can just add it to your skill. Simply mentioning it, or explaining that this is the interface you want to have in your skill, will trigger it in Claude Code. So let's build a simple example.

This simple example when invoked in Claude Code will look something like this:

And it even works in Cursor. Cursor's version of the same idea is called AskQuestion though I found that Cursor has compatibility with AskUserQuestion and can pick it up with no extra explanation.

Expanding grill-me

Matt Pocock's skill is very simple, and it gives an example of how the back and forth between agent and human looks like. So I decided to expand grill-me with the ask-question API.

Now instead of typing the question number and the answer, I can just pick the option that I want. I always have the option to write down a more specific answer if I want to.

I realize this is a personal preference, so I did not attempt to open up an issue on Matt’s repo. People have asked for this more than once (#19, #643, #798, #850), but none of it landed Matt is not a huge fan of these.

But that’s the beauty of skills. It’s just markdown files, you can modify them any way you like.

Making it work in Codex

I've been enjoying Codex a lot, but it doesn’t have th AskUserQuestion API. The skill is not going to be compatible so it always falls back to written quesitons when using it.

There's good news and bad news. The good news is that Codex actually has a similar API that we can use, called request_user_input. So we can simply expand our skill to handle Codex.

The bad news is that this only works in plan mode. Initially, I decided to handle this by writing the skill to instruct the user to switch to plan mode. But I dug a little deeper and found out that you can use interactive elements outside of plan mode as well. This feature has been behind a flag for some time.

Digging through GitHub I found several issues and PRs that reference this flag and suggest that it should be on by default, but this has never changed. Support landed in PR #12735. It was briefly pointed at default-on, then put back behind a flag in PR #13798. A later attempt to enable it by default, PR #24613, was closed.

I did not attempt to open up another issue. I guess the Codex team has a reason for not enabling this by default. The closest explanation I found is that structured questions can block model autonomy, especially during /goal.

The way I finally decided to handle this was to put the instruction to enable the flag right inside the skill. The skill itself will look into Codex, find the flag, and if it's not enabled it will ask the user if they want it enabled.

This is a one-time thing, so if you're trying to ship a skill with these interactive elements, you can add the following instruction. Until Codex ships this flag enabled by default, you can just have this in there.

You can also enable it for a one-off CLI session:

Testing other tools

I tried to see if this works in Claude Desktop. And while the interaction pops up, the description does not. This means that you're essentially choosing options but you're not really sure what it is that you are choosing, because you only see the headings or titles of the options. Which is not optimal.

I guess I could add another instruction to my skill so that if we're in Claude Desktop, it should first write down the options, and then you can use the interactive element to choose. But for my purposes I did not do that.

This is just a fun little experiment that I've played with in the last couple of days. I think it shows that when it comes to compatibility between different harnesses, we still have a long way to go. And I'm really hoping that this is not going to end up with a situation where every harness uses their own standards and nothing is compatible (looking at you, Anthropic). I really hope that stuff like skills and rules and agents files will over time converge to cross compatibility. But maybe I'm an optimist. I guess we'll see.