$ The Magic Prompt: A Minimal Invocation Into a Tested Human-Agent Workflow

There is a particular kind of prompt I find myself wanting more and more when working with coding agents.

I call it a magic prompt.

The name is intentionally a little misleading. There should be very little magic inside the prompt itself.

A magic prompt is not a giant wall of instructions. It is not the perfect combination of words that somehow makes an agent smarter. And it is definitely not another README disguised as a prompt.

A magic prompt is a small, portable invocation that takes a human and an agent from intent to a complete outcome.

You paste it into Codex, Claude Code, Cursor, or any other sufficiently capable agent, and the expectation is simple:

Take me from here to there.

Not 80% of the way.

Not until we discover that I was supposed to install three CLIs first.

Not until we reach a documentation page telling me to configure an account.

Not until the agent says, “Everything is ready, now manually follow these twelve steps.”

A good magic prompt owns the journey from A to Z. Zero to one. The whole process, as the person who invoked it understood it — and as the person who authored it intended it.

That changes how we need to design prompts.

What Makes a Prompt “Magic”?

Imagine I hand you a prompt for contributing to an open-source project. Say, one of Slack’s open-source SDKs. The desired outcome might be:

Get my environment ready and take me through making my first valid contribution.

There are dozens of hidden assumptions inside that sentence.

Do I have the repository? Do I have the correct runtime? Am I authenticated with GitHub? Do I have the required CLI tools? Does the project require signing a Contributor License Agreement? Is there a developer program I need to join? Are there forms I need to fill out, boxes I need to check? Do I have permission to create whatever sandbox, workspace, application, or token the project requires? What operating system am I using?

And then a second set of questions, about the other participant:

What tools does my agent have? Can it operate a browser? Can it execute shell commands? Can it see what I see? Can it complete an OAuth flow? Which decisions require me, and which can it make on its own?

Traditional documentation distributes the answers to these questions across README files, contribution guides, documentation sites, onboarding pages, tribal knowledge, and people’s heads. Then it relies on the user to assemble the puzzle.

A magic prompt should not.

Its contract is that the puzzle has already been assembled.

Four Perspectives on the Same Prompt

Before getting into the architecture, it helps to look at a magic prompt from every side of the table, because each side has a different expectation, and a good design satisfies all of them at once.

The human invoker. The person who pastes the prompt. Their expectation is safety and completeness. Safe, in that the prompt will not wander off, do something destructive, or leave their environment half-configured. Complete, in that it takes them to the outcome they were promised, not to a fork in the road.

The human author. The person who wrote the prompt and the workflow behind it. Their intent defines what “done” means. They know the process, and — this is important — they are biased by that knowledge. More on this later.

The agent. The harness that actually executes: Claude Code, Codex, Cursor, a cloud agent with computer use, whatever. The agent needs instructions it can act on, a way to discover what it is and is not able to do here, and a way to hand control to the human at exactly the right moments.

The required outcome. Not “the command returned zero.” The outcome as the invoker would recognize it: a thing exists, I can see it, it works, and I know what to do next.

When you design against all four, the shape of a magic prompt becomes fairly clear. It has a contract with the human, a contract with the agent, a layered structure, and a definition of completion that is stricter than most agents use by default.

The Human Contract

There still needs to be a boundary. A magic prompt cannot assume that absolutely nothing exists.

If I want to build something for Slack, I probably know that Slack exists. I may already have a workspace, or be willing to create one. If I want to deploy something to Vercel, I probably have or am willing to create a Vercel account. If I want to build on Wix, I have some idea what Wix is. I am not completely new to the platform; I have some access to it — a free tier, a paid plan, a developer account — and I know roughly where I stand with it.

These are reasonable human-level prerequisites.

But they should be explicit and, more importantly, minimal.

The magic prompt should not begin with an invisible dependency tree:

Before using this prompt, read this guide, install these five tools, create these resources, configure these environment variables, request access here, and then come back.

At that point it isn’t a magic prompt. It’s documentation with a prompt at the end.

Instead, configuration should become part of the execution.

Need a CLI? Install it. Need an SDK? Install it. Need authentication? Start the authentication flow. Need an API token? Determine whether it can be created automatically. If not, guide the human through exactly the intervention that is required, and nothing more. Need a browser? Use one, assuming the underlying agent has that capability. Need the human to approve something? Ask at the moment approval becomes necessary.

There is no assumption that everything must be pre-installed. There is no assumption that some step is too interactive, too manual, or too “outside the terminal” to belong in the prompt. Everything is up for grabs — including things that cannot be fully automated and require a browser, or computer use, or a human clicking a checkbox — provided the underlying agent can do it, or can guide the human to do it.

The distinction I find useful is between human prerequisites and machine prerequisites.

Human prerequisites should be minimized and declared upfront. Machine prerequisites should be owned by the workflow.

The Agent Contract

There is another side to this contract: the agent.

The magic prompt cannot assume every harness is identical.

Codex has one set of capabilities. Claude Code exposes another. An agent running inside an IDE has another. A cloud agent with computer use has capabilities that a local terminal agent doesn’t. Some agents can drive a browser; some can only ask you to open one. Some have persistent skills; some start from nothing every time.

So before doing the work, the workflow needs to understand its environment.

I think of this as the pre-flight.

Before execution, determine:

• What capabilities does this agent have?
• What tools are already installed, and are their versions compatible?
• What accounts or authentication already exist?
• What can be automated here, and what requires human intervention?
• What preferences has the human already expressed?
• Which prerequisites have already been satisfied?
• Which parts of the workflow actually apply to this environment?

This matters because a magic prompt should not blindly execute a tutorial. It should resolve a path.

If GitHub authentication already works, don’t teach me how to authenticate with GitHub. If the CLI is already installed and compatible, don’t reinstall it. If I already completed developer registration, don’t send me through registration again. If I don’t have something, don’t merely report that as an error. Determine how it becomes true.

And when the pre-flight discovers a gap — a missing capability, a tool that needs a permission the agent does not have, a preference it cannot infer — that is precisely the moment to ask the human. Not as a failure, but as a configuration step. “I can’t open a browser from this session. Can you open this URL and tell me when you’ve approved the app?” is a pre-flight outcome, not an escape hatch.

The pre-flight converts a generic process into a process for this human, on this machine, using this agent, right now.

The Prompt Itself Should Be Small

This leads to what I think is one of the more counterintuitive properties of a magic prompt:

The magic prompt should be lean.

We shouldn’t solve this by producing a 15,000-word superprompt. We already know how that goes. I argued in Your Docs Are Not the Prompt that project context is a secondary orientation layer, not the thing that drives an agent’s behavior. The same holds here. A giant prompt is a giant document with all the same problems: it drifts, it goes stale, it fights with the harness’s own instructions, and nobody can tell which part of it is actually load-bearing.

The initial prompt is an invocation layer.

It can contain some configuration and enough information to establish intent — who I am, what I want, what I already have, what I prefer — but its primary responsibility is to retrieve and initialize a larger workflow.

Something conceptually like:

I want to create X.
Use the latest workflow from Y.
My preferences are Z.
Run its pre-flight, resolve missing prerequisites with me,
execute the workflow to completion, validate the result,
and leave me with the next useful action.

The intelligence is not primarily in those sentences.

The intelligence lives behind them.

The Envelope Skill

Behind the magic prompt should be what I’ve been thinking of as an envelope skill.

You could call it a wrapper skill, an orchestration skill, an encompassing skill. The terminology matters less than the architecture.

The envelope owns the complete journey. It is the glue between the different steps and the different skills that need to be invoked, and it is the part that adapts to the specific agent running it and to the human’s preferences. This is where the actual magic lives.

It knows which smaller skills exist and how they fit together:

Magic Prompt
     ↓
Envelope Skill
     ↓
Pre-flight
     ↓
Environment / Account Setup
     ↓
Authentication
     ↓
Tool Installation
     ↓
Domain-Specific Workflow
     ↓
Validation
     ↓
Human Verification
     ↓
Next Action

Each of those pieces can then be skillified independently.

An authentication skill doesn’t need to know everything about creating a Slack application. A developer-registration skill — the one that walks a human through joining a developer program, creating a sandbox workspace, and accepting the terms — doesn’t need to know how the eventual project will be implemented. A local-environment skill can specialize in determining whether this machine satisfies the requirements and fixing it when it doesn’t.

The envelope composes them.

And importantly, it composes them conditionally. If pre-flight establishes that a prerequisite has already been satisfied, that branch disappears. If the agent can drive a browser, the OAuth branch runs one way; if it cannot, the same branch becomes a guided handoff to the human.

Two properties of the envelope are worth spelling out.

First, it should be fetched live. The prompt points at it; the agent retrieves the current version at invocation time. That is what lets the workflow be improved, templated, and optimized without anyone re-pasting anything. A magic prompt that embeds the whole workflow inline is frozen the moment it is shared.

Second, the smaller skills underneath it should be tested and evolved on their own, before the envelope depends on them. The developer-registration skill gets exercised in isolation until it reliably takes a new person through the developer program. Only then does it become a prerequisite the envelope can trust. The groundwork comes first; the composition comes after.

This is the same argument I made in Skills, Pipes, and the Unix Philosophy, applied one level up. Small, well-scoped pieces, each doing one thing well, composed by something whose only job is composition.

The prompt isn’t magical.

Composition is.

Skills Need Two Interfaces

There is another design property I think is important here.

Many agent skills are written exclusively for the agent.

But these workflows inherently have two participants: the agent and the human.

A good skill therefore needs instructions for both.

The agent side might say:

• inspect authentication state;
• detect the installed CLI version;
• verify permissions;
• attempt automatic configuration;
• validate the resulting environment.

The human side of the same step might become:

Your browser is going to open an authorization page. Sign in using the workspace you want to develop against. Approve these permissions. Tell me when the browser confirms authorization.

These are different interfaces to the same operation. The agent gets rules. The human gets a guide. Both are written by the author, in the same skill, so they can never drift apart.

This makes skills less like documentation and more like small collaborative protocols between humans and agents. The human is not reading a guide while the agent works; the human is participating in a step the agent is orchestrating.

Never Make “Manual” the Default Escape Hatch

One of the easiest ways to accidentally break the magic is the word manual.

Agents frequently reach some boundary and respond with something equivalent to:

I can’t complete this part. Follow this guide and return when you’re finished.

Sometimes human intervention genuinely is unavoidable. But human intervention and manual delegation are not the same thing.

If the human needs to click a legal acceptance checkbox, the agent can navigate them to it — the exact page, the exact box, what it means, and what to do afterward.

If OAuth requires the human to authenticate, the agent can initiate OAuth, explain what is happening, wait for completion, and verify authentication afterward.

If information is required — a workspace name, a region, a plan choice — the agent can ask for that specific information at the appropriate point, rather than stopping and pointing at a form.

The human should remain part of the execution graph. They shouldn’t be ejected from it.

A magic prompt therefore needs a useful rule:

When automation stops, orchestration should continue.

Completion Isn’t “The Command Succeeded”

There is also a surprisingly important question: when is the magic prompt finished?

Agents tend to define completion technically. The repository exists. The application was created. The deployment succeeded. The command returned zero.

But that isn’t necessarily the human’s definition of completion.

If I asked an agent to create something, I probably need to see it.

Open the application. Show the deployment. Take me to the relevant dashboard. Render the result in my browser, or capture it and show it to me. Verify that the thing we created actually behaves as expected — send the test message, hit the endpoint, trigger the slash command.

Completion should include a human-observable outcome whenever one exists.

And even that isn’t quite enough.

A Magic Prompt Should Leave Another Door Open

Suppose the workflow successfully created my development environment.

Great. Now what?

Traditional setup documentation often ends there:

Congratulations! Your environment is ready.

But from the human’s perspective, this may be precisely the point where the interesting part begins.

The magic prompt should establish the next interaction. For example:

Everything is configured and validated. You can now ask me to find a suitable starter issue in this repository and prepare a contribution.

Or:

Your Slack app is installed in your sandbox workspace and responding. From here, you can ask me to implement your first slash command.

Or:

Deployment is complete. You can now describe the change you want to make and I’ll modify and redeploy it.

Don’t assume the process is done because the thing we set out to create exists. The product isn’t merely the artifact. The product is also the new capability the human has acquired — and the very next sentence they can say to their agent to use it.

We Made the Same Mistake With Documentation

A lot of this reminds me of how we’ve historically written developer documentation.

Documentation is usually written by somebody for whom the environment already works.

That’s a dangerous starting point.

The author already has the correct runtime. Their SSH keys work. Their accounts exist. They signed the agreement six months ago. Their machine contains some tool they installed for an unrelated project three years ago. They know what the internal terminology means — what a “workspace” is here versus there, what “sandbox” means in this company’s vocabulary, which of the three dashboards is the one you actually use.

Then they write:

npm install
npm run dev

And everything works.

For them.

We compensate for this by expecting expertise from the reader. A sufficiently experienced engineer can usually bridge the missing pieces. They search for an error. They recognize that a credential is missing. They know what OAuth is. They infer which account they should use.

But this isn’t evidence that the documentation was complete. It’s evidence that the human was capable of repairing it.

Every system, every company, every community has its own way of doing things — its own onboarding rituals, its own forms, its own naming. To the author these are obvious. To a new person in a new environment they are foreign, and the “obvious” steps are exactly the ones that go unwritten. We were reckless about prerequisites, reckless about how our documentation fit into the puzzle in different people’s heads, and we relied on experts to close the gap.

Agents give us an opportunity to stop relying on that repair mechanism — but only if we stop carrying the old gaps into the new medium.

Test the Empty Workspace

There is a simple test for magic prompts that I think should become standard:

Run them from nothing.

Not from the machine where the workflow was developed. Not from the author’s workspace. Not from the environment where everything has been configured for six months.

Use a clean environment. A fresh container, a new machine, a throwaway account. Assume the human has only the minimal prerequisites that the magic prompt explicitly declares — and nothing else.

Then run the whole thing.

Every time the workflow encounters an undocumented assumption, that assumption becomes one of three things:

1. an explicit human prerequisite,
2. part of pre-flight,
3. or another skill the workflow needs to own.

Repeat until there are no accidental gaps.

Then do it again with a different agent, because the pre-flight branch that works in Claude Code may not be the one that works in Codex.

This is almost like integration testing, except the system under test is a human-agent workflow. It is the same discipline I described in The Feedback Loop Series Part 3: AI Agents, pointed at a different target: instead of testing whether the agent produced correct code, you are testing whether the workflow reliably gets a stranger to the outcome.

When I build these flows honestly — mimicking the new user fully, on a clean workspace, with their setup and not mine — there is no gap left for an expert to bridge. The gap only exists when I skip that step and build on top of what I already have.

Prompts Are Becoming Entry Points

We spent years treating prompts primarily as instructions.

I think that mental model is becoming insufficient.

As agents gain shells, browsers, computer use, APIs, persistent skills, authentication, and the ability to operate external systems, a prompt can increasingly behave like an entry point into executable knowledge.

That changes what good prompt engineering looks like.

The interesting problem is no longer:

What exact words will make the model produce the best answer?

It becomes:

How do I package a process so that a human can invoke it from an unknown environment and reliably reach the intended outcome?

That includes instructions. But it also includes capability discovery, dependency resolution, configuration, authentication, conditional execution, human interaction, validation, recovery, and handoff.

The magic prompt is simply the smallest interface into that system.

The Magic Is Everything Behind the Prompt

This is also why I think publishing a collection of magic prompts without the infrastructure behind them misses the point.

The valuable artifact isn’t:

Paste this into your coding agent.

The valuable artifact is everything required to make that sentence trustworthy:

• The skills have been designed.
• The prerequisites have been identified and minimized.
• The branches have been considered.
• The human interventions have been designed, not delegated.
• The workflow has been tested from a clean environment.
• Failure states have paths forward.
• The outcome can be validated and shown.
• And the human knows what to do after it succeeds.

Only then can the invocation become tiny.

That’s an interesting inversion. The more engineering we put behind the prompt, the less prompt the user should need to see.

And perhaps that’s the best definition:

A magic prompt is a minimal invocation into a tested, adaptive human-agent workflow that owns the path from prerequisites to a verified outcome — and leaves the human ready for what comes next.

The magic isn’t that the prompt knows everything.

The magic is that the user no longer needs to.

In a follow-up, I plan to make this concrete: an actual magic prompt for a first open-source contribution to one of the Slack SDKs, with its envelope skill and the full skill tree underneath it — developer registration, sandbox workspace, CLI setup, authentication, and the contribution itself — tested from an empty workspace.