Teaching an agent

Any capable model can write vDesign documents once it has been shown the format. What shows it is the vDesign skill: a set of plain Markdown files with a few example documents. It is written for no model in particular and carries no vendor’s conventions.

What the skill holds

• The instructions: the format in one screen, the rules that decide whether a design is any good (use tokens, place things relative to each other, keep text inside its box), and how to edit rather than rewrite.
• The reference, which these docs publish unchanged: expressions, nodes, edits and motion.
• Examples: complete documents that parse, resolve and draw.

Three ways to give it to a model

Over MCP, there is nothing to install. vDesign’s MCP server serves the skill two ways, and its instructions tell the assistant to load it before its first write:

• As a skill, through the MCP Skills extension (io.modelcontextprotocol/skills). An assistant whose app supports the extension loads it the way it loads any skill: the app lists it from skills/list, reads its files at skill://vdesign/…, and checks each one against the digest and size the server gave.
• Through the vd_skill tool, for every other assistant. It returns SKILL.md first, and any other file by its path (reference/grammar.md) only when asked.

Either way, a conversation pays for the grammar only once it needs it. See MCP.

As a skill folder, for an agent that loads skill directories. The folder is SKILL.md, with frontmatter naming it and saying when to use it, beside reference/ and examples/. The agent reads SKILL.md up front and the reference files when a task calls for them. Copy the folder, keeping its name vdesign, to where your agent reads skills: Claude Code reads ~/.claude/skills/ (or .claude/skills/ in a project), and many other clients read the shared ~/.agents/skills/ (or .agents/skills/). Check your client’s documentation for its own folder.

As a system prompt, for anything else. The same content is also built as one flattened file, the instructions followed by every reference file and the examples: download the system prompt. It costs its full length on every turn rather than loading the reference on demand, which is the price of working with any model at all.

An agent that reads llms.txt finds one at /docs/llms.txt, listing a plain Markdown copy of every page here, and llms-full.txt puts what a model needs in one file, starting with the system prompt.

What a model writes

A model asked for a new design replies with a whole document. Asked to change one, it replies with edit statements rather than the document again:

set $gap = 40
set hero.title size=34 weight=700

Each statement is applied as one operation, so it can be undone as one step, and nothing else in the document is touched. Edits has the full dialect.