Knowledge

Recursica’s agents need more than a theme to design a good screen. A theme tells an agent which colors and fonts to use. It doesn’t tell the agent whether to use a button or a link, how many main actions one page should have, or what a table should do when it runs out of room. Designers usually keep those decisions in their heads, and an agent can’t guess them.

So Border UX wrote them down. The knowledge repo holds Border UX’s design knowledge as skills, which are plain text files. It’s free to use under the MIT license, and the agents read it before they build or review any screen.

Skills

The knowledge repo is made of skills. A skill covers one topic, such as buttons or tables, in a single file named SKILL.md. Each skill has its own folder inside the skills folder, and the files follow Anthropic’s Agent Skills format, so any agent that supports that format can use them.

Every SKILL.md file starts with a short header that gives the skill’s name, license, and description. An agent reads the description to decide whether the skill applies, so the description lists the situations the skill covers, in the words people actually use. It also names the skill to use instead for nearby situations. The button skill, for example, sends questions about navigation to the link skill.

The rest of the file is the guidance itself: when to use something, when not to, and what to use instead. The guidance is specific enough to check. One example from the button skill: a button that takes the user to a new page should be a link, no matter how it looks.

Any folder that contains a SKILL.md file counts as a skill, so the repo has no separate list to maintain. Recursica reads the list of skills straight from the repo.

The repo also has a docs folder with component pages written for people. Some of those pages are out of date. When a page in docs and a skill disagree, the skill is correct.

The design router

Before an agent works on a screen, it reads the design router skill (recursica-skill-design-router). The router tells the agent what order to make decisions in, and which skill to check for each decision.

For every component an agent puts on a screen, it reads two skills:

• The component skill explains the component: which versions and states it has, and how to make it accessible.
• The design-rules skill for that kind of screen explains whether the component belongs there at all.

Agents that skip the design-rules skill often build screens where every component is correct but the screen as a whole is wrong.

When two skills disagree, the router decides which one wins:

• The design system always decides how things look.
• Guidance that says “don’t” beats guidance that says “you can”.
• A design-rules skill beats a component skill on screen layout.
• A component skill wins on which versions of the component exist.

If no skill answers a question, the agent asks a person. It doesn’t guess, and it doesn’t copy a pattern from some other design system.

Editing skills

Anyone who copies the repo can change the skills. To change a skill, edit its SKILL.md file. To add new research, add a new folder with a SKILL.md file in it. The contributing guide explains how to format it. The agents use a change the next time they run, with nothing to build or deploy.

Not every change has to be made by hand. Alan, our knowledge agent, reads design feedback from Snippy and looks for gaps or mistakes in the skills. When he finds one, he suggests a fix in a pull request or opens a GitHub issue, and a person decides whether to accept it.

The agents themselves are in the agents folder. Meet the team to see what each one does.

Skill categories