Why Writing AI Skills Is Design Work

Nov 14, 2026AI Integration, AI Mindset, AI Practice, Craft, Systems, Tools

TL;DR:  Writing an AI agent skill draws on three disciplines at once: design, linguistics, and orchestration. The skill is the seed, and it only grows well in clean data and a well-arranged system.

 

An orange that tastes like nothing

A LinkedIn post by Andreas Markdalen tells people who are building their first AI-native design system to start with Bruno Munari’s tribute to the orange. Munari saw the orange as perfect design. The peel protects the fruit and looks good doing it. The segments separate cleanly and come in bite-sized portions. The seeds travel inside the package. Every feature has a function, and nothing is there as decoration.

Andrea’s post then turns to AI. It describes oranges grown in poor conditions that taste like nothing, and it calls the markdown file the new source of systemic truth, a seed we can program with meaning, purpose and intent. If you are new to building agents, a markdown file is a plain text file with light formatting such as headings and lists, and an agent reads it as its instructions before it starts work, so it holds the role, the rules and the steps the agent follows.

I read it and nodded, because writing those seeds is how I spend a large part of my week. I also had a question. A seed never grows alone. It needs soil, and someone has to tend it.

The seed is a design object

When I write a skill, I make the same choices I make when designing a layout. What comes first. What the reader sees at a glance. What stays out. A skill has a user, a job to be done and a list of ways it can go wrong. The user happens to be an agent that follows every word and never asks what I meant.

Munari’s test applies directly. Every line should have a function. If a sentence in a skill file changes nothing about the output, it is decoration, and it costs attention every time the file loads. I now cut lines the way I cut elements from a poster.

“A skill file is the one design brief your reader follows to the letter.”

I wrote recently about drawing a schema just to keep my skills files from contradicting each other. That drawing was a design act. It showed me hierarchy, flow, and clashes before they became bugs.

The seed is also a sentence

Skills are written in language, so the craft of language decides how they behave. “Should” and “must” produce different agents. A verb like “check” leaves the agent to decide what checking means. The order of instructions changes which one wins when two collide. Ambiguity that a human colleague would quietly resolve becomes a behaviour the agent commits to.

I am currently designing a skill that reviews academic writing. Take the instruction “review the argument.” It sounds clear and produces polite, general comments. I replaced it with “for each claim, find the supporting evidence in the text and quote the line. If none exists, flag the claim as unsupported.” The next review changed shape. Comments became numbered findings tied to specific lines, and the agent stopped praising arguments it could not trace.

Other behaviours started the same way. Reviews now flag conflicts between chapters and leave the source note untouched, and each of those began as a sentence I had to word carefully. Writing them felt closer to editing a paragraph for a journal than to programming.

The soil is data

This is the part the seed metaphor leaves out. An AI skill can only review what it can access and read. For a long chapter, that means the chapter itself, the earlier chapters it has to stay consistent with, the dates that show which draft is current, and the standards it reviews against. In one AI skills review test, my agent caught a contradiction between two chapters. That was only possible because both sat in the same folder, in readable text, with clear names. That is also why I convert PDFs to markdown first. A markdown file is clean, well-structured text, while a PDF stores layout for the eye, so columns, headers and footnotes can come out in a different order depending on the tool that reads it.

Now picture the opposite. Three versions of a draft in one folder. Notes that disagree with each other. A file called “final2”. A well-written skill pointed at that folder will review the wrong version and sound confident about it. I wrote earlier about how AI can sound sure of itself when something has quietly derailed it. Messy data is one of the quietest ways to derail it.

Clean data means named, dated, versioned and readable by a machine. Designers already know this discipline, even if we rarely call it version control. Design is iterative, so one project leaves behind dozens of versions: the first sketch, the revised layout, the client’s favourite, the one that shipped. We keep them because the path matters, and we label them so we always know which one is current. An agent cannot tell which draft is current unless names, dates and folder structure tell it. Data hygiene rarely feels like design work, yet it decides whether the skill’s careful wording ever reaches the right material.

The garden is orchestration

Seed and soil still need a gardener. Orchestration decides which skill runs when, what each one reads, what it hands to the next, and where a human steps in to judge. This is where attention becomes a design material. If every skill ends with an open question, I become the bottleneck. If each one hands back a structured report, I can decide quickly and well.

Orchestration also shapes how knowledge ages. A skill that reads a living folder improves as the folder improves. A skill that reads a stale folder spreads old thinking efficiently. Nobody sees the problem until the fruit arrives.

What I would tell a designer starting today

Treat your first skill like a brief you will be judged on. Cut every line that changes nothing. Read each instruction as a literal-minded stranger would. Check what data the skill touches before you polish its wording. Then draw how the skills and files connect, so you can see the whole garden at once.

Munari ended up with an orange because every part had a job. The same standard applies to a markdown file, the folder it reads from and the system that runs it. The ambition from Andrea’s post holds for all of it: every slice has to be juicy, otherwise it is not worth the peel.

What is one line in your latest skill file that you could delete without changing a single output?

Hello! I'm Linus, an academic researching cognition, behaviour and technologies in design. I am currently writing about AI in Design, academia, and life.