# DESIGN.md vs SKILL.md: what each file does

Updated 2026-11-21 · https://briefatto.com/guides/design-md-vs-skill-md/

DESIGN.md holds your project's design guide, and SKILL.md holds the procedure your agent follows. Briefatto Board ships both: its SKILL.md tells the agent how to run the board, and the DESIGN.md it freezes is the guide the agent reads before any visual work.

## DESIGN.md and SKILL.md side by side

|  | DESIGN.md | SKILL.md |
| --- | --- | --- |
| Holds | Your design guide: layout, components, type and voice, plus a generated block of exact styles | The procedure: which board commands to run, in what order |
| Lives at | The project root | `.claude/skills/briefatto-board/` after `board install` |
| Changes when | Your brand changes, through `board freeze`, which stamps a new version | Briefatto Board ships a release |
| The agent reads it | Before any visual work | When it runs the board |

## How one points to the other

`board install` places the skill under `.claude/skills/` and writes a marked block into AGENTS.md and CLAUDE.md that points to it. After `board freeze`, the same block tells the agent to read `DESIGN.md` before any visual work and to run `board check` on every piece before handing it over.

`board freeze` records source wording and exact styles from a fresh render in a generated DESIGN.md block, validates the authored guidance against those values, then stamps and archives the guide.

## Questions and answers

### Do I need both DESIGN.md and SKILL.md?

Yes, and you write neither from a blank page. `npx briefatto-board install` adds the skill, and `board freeze` stamps your DESIGN.md.

### Is SKILL.md a Briefatto format?

No. A skill is a folder with a SKILL.md file, a convention that Claude Code, Cursor, Lovable and OpenCode describe in their own documentation.

### Can I put my design rules inside SKILL.md?

Keep them in DESIGN.md. The skill is the procedure; DESIGN.md is your brand, and `board freeze` versions and validates it.

## Try it

```
npx briefatto-board install
```

Briefatto Board is free and open source under Apache-2.0: https://github.com/Briefatto/briefatto-board

## Related guides

- [DESIGN.md vs a design system: what is the difference?](https://briefatto.com/guides/design-md-vs-design-system/)
- [Impeccable vs Taste Skill: what a blind test showed](https://briefatto.com/guides/impeccable-vs-taste-skill/)
- [A free, open-source DESIGN.md tool for coding agents](https://briefatto.com/guides/design-md-open-source/)
- [Briefatto Board vs Impeccable, Taste Skill and Hallmark: the blind test](https://briefatto.com/guides/impeccable-vs-taste-skill-vs-hallmark-blind-test/)

## Sources

- https://github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md
- https://github.com/Briefatto/briefatto-board/blob/main/README.md
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/standing.ts
- https://cursor.com/docs/skills (checked 2026-11-21)
- https://docs.lovable.dev/features/skills (checked 2026-11-21)
- https://opencode.ai/docs/skills/ (checked 2026-11-21)
- https://code.claude.com/docs/en/skills (checked 2026-11-21)
- https://github.com/Briefatto/briefatto-board/blob/main/LICENSE
