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.