Last week I tried to talk you into graduating from the chat tab to an agent. This week is the natural follow-up. Now that you’ve got one, how do you actually brief it so it doesn’t return mush?
Prompt length paradox
You likely know (or maybe you are) a colleague who says “let’s hop on a quick call”. It’s not that the keyboard is broken. It’s that we don’t have the patience to sit down and shape a concise message. Braindumping is naturally easier than distilling thoughts.
I didn’t know the author, but I really like this quote that explains the brevity concept well.
“I would have written a shorter letter, but I did not have the time.”
The same pattern shows up with agents. I’ve seen people fire off a two-line prompt, get a mediocre answer back, and conclude “the model isn’t there yet.” It’s not that the longer the prompt the better. Long prompts can be noisy. But at least they share more context.
From my experience with agents you should either “jump on a quick call” to braindump unstructured idea before it fades away or write a structured ask with a good investment of time. The middle ground is always shaky.
Voice is the natural human-to-agent channel
Every major AI app already supports voice-to-text. The easiest first step this week: press the mic button and start talking to your agent the way you’d talk to a teammate at the next desk. Just go at it – don’t be shy.
There are tools that make this even more transversal. The one I use daily is Wisprflow. It learns your vocabulary, persists memory across mobile and laptop, adjusts to your style, and even reformats based on the app you’re in (formal for emails, casual for Slack, code-aware in Claude). It’s the closest thing to “thinking out loud, directly into the machine” I’ve tried.
Hold one button. Talk to any textbox. That’s it.
Other strong players worth a look:
Superwhisper – runs fully local on your machine. Great if you care about privacy.
Plaud - a physical pin that transcribes live meetings or your voice notes. Different use-case, but the same underlying bet.
If you’re not talking to your laptop already – please join the weirdo club. Pick one. Install it today.
The hard part: when the output disappoints, look inward
Unpopular opinion: when an agent returns junk, I don’t blame “Opus 4.7 got degraded this week”. That’s the easy story. I default to assuming I prompted badly.
When I dig in, it’s almost always one of three mistakes I keep making.
A/ I asked too much in one go
The temptation is to share the whole idea with micro-nuances and multiple functions and outputs and hit send. Don’t.
Break the problem into layers and solve them in order. Dummy skeleton first. Core logic next. Wiring them together later. If you’re not time-pressured, do not try to one-shot something non-trivial. The post-fixing part will be tough.
I found helpful asking myself if there are foundational blocks I can nail down first to put the agent on the same page: a design system, a core calculation, the database schema and how tables interconnect, a short list of project-wide rules. Front-loading these saves you from re-explaining the same context in every prompt.
B/ I didn’t bring enough taste
The output quality jumps when you bring your own deliberate decisions into the brief.
A difference between “one-shotting” a screen with and without reference is significant
AI makes thinking optional. That’s the trap. The thinking is what actually makes the difference. The model is an extension of you - if you show up vague, you get vague back. If you show up with taste and intention, the difference is visible.
A raw example. Here’s a recent prompt from a real mid-discussion with my agent, for context on what I mean by “specific”:
“let’s remove the 3 cards we have and instead add one full-width card based on 2 references: strain reference for card style, the calendar view for content.
a white card (#FEFFFF) with outer shadow
gray fire icon + title (#616265) “Weekly streak” + an arrow at the upper right corner that means we can open the details by clicking
below title we have days of the week (Mon - Sun) with a bottom line
under each day we should have a date (like “6”) and an empty circle below. future dates have #909194 color, past #202124, selected/active = accent color (#3EAAFF)
successful circles filled with selected accent color (#3EAAFF) and a white tick
selected day has a white oval uniting both the date number and the circle. oval has outer shadow”
That’s not a magic prompt. That’s just me having thought through what I actually want to see as the output down to colors and visual structure of one card.
It’s slower. But more intentional and reliable.
C/ I handed over the wrong format
The content of your reference matters, but so does the format.
Rule of thumb: the more “texty” the format, the better.
100-slide PPTX as the source for a Q&A agent → bad. It’s a giant XML soup, and the model burns context wading through it to find two bullets on slide 84.
PNG / JPG → meh. The model has to decode pixels into characters before it can even start thinking.
SVG → better. This image type is also “text”. Meaning it’s more native to agents than JPG/PNG.
Markdown (.md) → agent-native. Zero overhead, light, rich enough for titles, tables, lists, links. Both easy to read and to produce.
HTML page → great. It’s a markdown on steroids. Content + visuals. In text.
The shift in mindset is: if you have a lot of context to share, your prompt shouldn’t be one long wall of text. It should be a short prompt that references well-structured text-first files. The hour you spend turning a sprawling doc into a clean .md will pay off every single time you point an agent at it.
The tech community is now leaning more into HTML as the agent’s ideal output. A Claude Code engineer at Anthropic recently posted a strong case for ditching markdown in favour of HTML as the default thing an agent hands back to you. Full piece here - worth the read.
Why HTML is cool:
HTML = everything. Whatever cool interactive things/artifacts Claude Chat created for you – it’s all HTML. Any page on the internet is HTML.
HTML is just richer. Markdown gives you headers and bullets. HTML gives you tables, charts, colour, layout, sliders, drag-and-drop, side-by-side comparison grids. For most office work, that’s the gap between a doc you’ll skim later and one you’ll actually use.
People will actually read it. A 200-line markdown report gets ignored. An HTML file has depth, built-in data, animations. You can basically send interactive reports/dashboards.
The real unlock is two-way. You stop reading the output and start interacting with it. Imagine you are selecting a visual style for a dashboard you’re building. Get a file that tweaks as you interact with it. Click buttons. Drag cards. Tune sliders. Then a “copy as prompt” button packages your decisions back into a brief for the next round.
A few examples that come to mind:
C-Level updates. KPIs, dashboards, highlights – perfect HTML candidates. Your regular bullet-points can become alive.
Email or message template tuning. If you send company/department-wide coms, this is a no-brainer.
Decisions that don’t fit a text box. Brand colours, timeline weights, criteria scoring. Things where a slider or a click beats typing five paragraphs of “no, make that box yellow too”
An Idea For This Week
Download Wisprflow and start talking to your agents the way you’d talk to a colleague. On the bus. In the kitchen. On a walk.
Break the next big task into 3-4 layers before briefing the agent. Skeleton first, logic next, wiring later. Almost never try to one-shot.
Do the thinking. The references and the taste bring 80% of the result. It’s hard. But worth your time.
Give markdown, ask for HTML. Make an experiment. Try packaging your context in markdown files and asking your agent to return html as the output.
The model isn’t getting dumber. I just get lazier. Both are fixable. It’s just that one of them faster than the other.
This Week I Shipped
A more experimental week - I spent it trying to build my iOS app from my phone.
What unlocked it: XcodeBuild MCP + remote control inside Claude Code. In short - you can kick off a Claude Code session on your laptop (where all your files, tools, and simulators live), and then use your phone as a remote. Typed commands on while on the bus, get responses back in a chat. Your laptop is doing the work; your phone is just the interface.
Mind-blowing what’s possible. Having zero social life is becoming way easier :)
What’s the one thing you tried to one-shot recently that bit you? Reply on this e-mail, I read everything.