system-design-skill
A skill that makes an AI agent ask questions, do the math and plan for failure before it designs a new system.
All projectsExplore the projectSource on GitHub
- Problem
- AI agents asked to design a new system already know a lot, but they skip the habits that protect you. They design without asking anything, guess the load without showing the math, and pick backups that don't match how much the data matters.
- Decision
- Before writing a single rule, I tested agents with no skill and listed exactly what they skipped. The skill only teaches those gaps and leaves out what the models already do well.
- Result
- With the skill, the same three designs went from passing 1 of 18 checks to all 18, and it held on two systems it had never seen. It works in OpenAI Codex too, with no changes.
- Role
- Sole developer
- Period
- 2026 to now
- Stack
- Markdown, Agent Skills, Claude Code, OpenAI Codex
Why I built it
I’m fairly new to system design, so I learned it the slow way first. Over five short sessions I designed a link shortener, a chat app and a bulk email job with Claude as a tutor, and wrote down every idea I got wrong or missed. That gave me 25 rules. The plan was to turn them into a skill, so that any agent starting a new project would follow them too.
What the models already knew
Before writing any of it, I gave three fresh agents a design problem each, with no skill loaded. They were better than I expected. They kept things small, used database constraints to stop duplicates and moved slow work into background jobs without being told. Teaching them that again would just be noise.
What they skipped was the process around the design. None of them asked a single question before designing. Their estimates came with no working shown, like “a few thousand a day at most”. And the photo sharing design called the club’s photos irreplaceable, then backed them up once a night. One bad evening could have lost a whole day of them.
What the skill does
The skill is a single Markdown file with no scripts, so it loads the same way in Claude Code and in Codex. When someone asks an agent to design something new, it has to
- ask at most ten questions, each with a default you can accept in one word
- show the arithmetic for peak load, storage and monthly cost before choosing any parts
- write a
DESIGN.mdwith a backup goal for each kind of data, a walk through what fails, and a number for when each thing it chose not to build should be added - reply with a short message naming the three to five decisions that would be hardest to undo, and wait for a yes before any code is written
The results
I scored every run against the same six checks, covering asking first, showing the math, protecting data by how much it matters, giving numbers for later work, covering failures outside the code and flagging decisions that are hard to undo.
| Scenarios | Without the skill | With the skill |
|---|---|---|
| Habit tracker, webhooks and photo sharing | 1 of 18 | 18 of 18 |
| Theater ticketing and greenhouse sensors, which the skill never saw while I wrote it | about 2.5 of 12 | 12 of 12 |
| Theater ticketing in OpenAI Codex, on the same model both times | about 0.5 of 6 | 6 of 6 |
The photo design is the change I like most. With the skill, it copied every original to a second provider within minutes, and set an alarm for any photo that went more than an hour without a backup.
What testing changed
The first draft asked 18 or 19 questions per design. I assumed the agents were overdoing it, but the research showed my own template was the cause, since it had a slot for about 17. I cut it to ten and moved everything else into a list of assumptions.
I also asked the designs to be shorter. That did nothing at all, and the next round came out longer than before, because the sections that earn the score take room. So instead of fighting the length, I moved it. The full design now goes into a file, and the chat reply dropped from about 3,000 words to about 340.
What it doesn’t prove yet
Each scenario ran once, and I scored the runs myself. The raw outputs are in the repository so anyone can check my scoring. It should work in Grok’s command line tool too, since that reads the same format, but I haven’t tested it there.