Human-friendly now, AI-friendly next: Improving the design system one skill at a time

Step one: let AI do the repetitive work, but not blindly. How I turned our documentation checklist into a skill.

This week, a tiny documentation request sent me down a big Design System rabbit hole. And it made me ridiculously happy.

For the first time since our Design System team was dissolved, a designer wanted to add documentation to our website 🎉

To help him, I went looking for our static documentation checklist.
You know, the way you did it what feels like years ago, in the pre‑AI era.

When I went to rescue it, I realised the file had been archived, together with other design-system-team-owned resources.

So I did what you do now: I opened Claude and asked it to turn the checklist into a skill.

Fasert, but not careless. The skill speeds up the repetitive work while keeping space for human judgment.

The skill

I always enjoyed doing the documentation bit, but I know for most people that is... painful.

So the opportunity was quite clear: take our very detailed checklist and turn it into something to automate this process.

And it worked. Pretty much on the first take. The only thing I had to add was how to document the React part, which was missing from the original checklist. Thirty seconds later, the skill was done.

Now, anyone with a component that needs documentation can start from wherever they are:

One skill. Four modes. The contributor chooses how to start.

• Draft: Takes a Confluence page, a draft, or a voice-to-text blab and transforms it into documentation that follows our standards, while flagging what is missing.

• Figma: Reads the component, extracts variants and properties, then interviews the contributor to fill in the usage, accessibility, and content guidance.

• Code: Uses the component implementation and API as a starting point. This should scale well as we move toward more code-first workflows.

• From-scratch: An interview mode that asks the right questions step by step and turns the answers into something polished.

After my testing round, the Accessibility tab output went straight into the official documentation. Turns out the old checklist wasn't so bad after all. It was just too hidden and the process… too manual. Now it's doing its job well.

Why create a documentation skill

While we are in a bit of debt regarding being AI-friendly, our documentation website remains a good source of truth. Not only for fellow humans, but also as part of the AI workflows Engineering Ops is creating (like the Design System skill that uses the existing documentation as a reference).

That’s one small step of many to make Design System resources part of a more collective brain. And discoverable! Everyone is using Claude now. And Claude, my friend, reads the design system.

Which means a design system is more important than ever. But it’s NOT getting the attention it deserves. I don't say that because I’m biased.

A more AI-friendly scenario

The documentation skill was an easy win. But fixing the human-facing layer is only one part of the puzzle.

If the “new normal” for accessing Design System knowledge is through AI, we need to make sure the Design System is built for that, too.

And I’ve become obsessed with finding ways to make it more AI-friendly whenever I have some time.

My next experiment is already in the making: a design-system-bridge.skill.

With the human-friendly part done, my next focus is adding a more AI-friendly layer to get better outputs

• A self-updating component-rules.md file straight in our repo, linked to the existing Design System skill

• Detecting missing Figma ↔ code connections and making it easier to map them (yes, we still use Figma!)

These should give AI better context, and we (designers, engineers, product builders… you name it) can finally get better outputs with it. If we don’t fix this, the AI will just… keep getting it wrong. And guess what gets blamed.

Bottleneck who?

We've all heard it at some point. The Design System is a bottleneck.

But we are at real risk of this becoming true if the AI comes up with poor outputs over and over again. (I'm feeling that now as a DS user!)

So here is what I think: better outputs start with better foundations.

And our foundations were not built with AI in mind. With no dedicated team and everyone focused on shipping with Claude (AKA using them every day), they are in desperate need of a... makeover.

• Our human docs? Great! ❤️ (They even appeared in a few social media posts)

• AI knowledge layer? Not quite there yet 💔

Which means the way we structure and expose our knowledge has become even more important.

No more worrying about “is anyone even reading this?” The AI is 👀
And it needs to find the right answers.

---