Brand skills

A brand skill is a brand's standards for one discipline, written as an Agent Skill and carried with the design system. An Agent Skill is a Markdown file, with optional text references, in the open Agent Skills format. Lolly keeps the brand's text as written and hands the skill to the agent doing the work: through Lolly's MCP server, or as a folder for an agent tool on your own machine.

This page is for brand owners who write standards and for people who connect agents to Lolly. A brand skill guides. A skill never gives a pass or a fail: the design system's house rules are what Lolly checks.

Three layers of guidance

Each layer keeps to its own subject. A brand skill does not explain a tool, and the Lolly skill does not speak for a brand.

Lolly also generates a baseline skill for every design system from its design brief: named colours, approved pairings, type, logos per surface, icon themes, media families and the house rules Lolly checks. Its name ends in -baseline (lolly-demo-baseline for Lolly Demo). The baseline is marked as generated and states values rather than intent. The brand's own skills take precedence on anything they cover. Lolly writes the baseline on request and does not store a copy.

The Lolly Demo skills

Lolly Demo, Lolly's own example brand, carries three public skills. They are the worked example on this page.

List them from a checkout with the Lolly Demo content profile:

LOLLY_PROFILE=lolly-demo lolly system skills

Lolly Demo brand skills

lolly-demo-brand             brand          draft     public    r1.0  Lolly Demo brand standards
lolly-demo-motion            motion         draft     public    r1.0  Lolly Demo motion
lolly-demo-photography       photography    draft     public    r1.0  Lolly Demo photography
lolly-demo-baseline          generated baseline from the design brief

Read one: lolly system skill <name>

Write a skill Lolly carries well

• Plain Markdown is enough. Frontmatter is optional. When a file has none, Lolly supplies name and description from the catalog record whenever it hands the skill out. When a file has its own frontmatter, Lolly keeps the brand's fields and adds only its own metadata keys.
• One discipline per skill. Overall brand, photography, motion, iconography and so on, each in a skill of its own. An agent editing a photograph then reads the photography skill, and an agent making a QR code does not.
• Write the overall skill first. A discipline skill can open by sending the reader there, as the Lolly Demo photography skill does: "Read the Lolly Demo brand standards first."
• One file or a folder. A single SKILL.md, or SKILL.md with up to 16 reference files one level down in references/ (.md, .json, .csv or .txt). Keep SKILL.md under about 500 lines and about 5,000 tokens, and move detail into references.
• No scripts. A skill with a scripts/ folder or a code file (.js, .py, .sh and the like) is refused with a reason. A brand skill is guidance, not a program.
• Images by catalog asset id. Write a link whose target is the asset id, such as the horizontal lockup. Lolly points the link at the catalog file when it hands the skill out. Image files inside a skill are refused.
• State measurable facts plainly. "Liquorice #09141a is the ink" can be compared with the tokens; "a dark, confident ink" cannot. Write hex values, the design system's own font family names, percentages and milliseconds as they are.
• Keep to brand intent. Lolly flags lines that ask the reader to set aside other instructions, claim permissions, list allowed tools or ask the reader to run code. A skill cannot grant any of those.
• Prefer catalog assets to external links. Lolly never fetches an external link and cannot tell whether an agent can open one. An owner can record that an external URL means a catalog asset (references in the record below).

The start of the Lolly Demo photography skill shows these habits:

---
name: lolly-demo-photography
description: How Lolly Demo photographs look and how to grade, crop and treat them. Use when choosing, editing or grading a photograph for Lolly Demo work, in Darkroom, Filter or Design.
---

# Lolly Demo photography

Read the Lolly Demo brand standards first. This skill covers photographs only.

## Grading

- Start from [Standard Slide](lolly/luts/slide-standard), a neutral daylight look. Use [Vivid Slide](lolly/luts/slide-vivid) for food and sweets, and [Fine Mono](lolly/luts/mono-fine) for black and white.
- A duotone uses two Opal colours, dark first: Liquorice with Spearmint, or Spearmint with Pandanus.

The catalog record

A skill is a catalog asset of type: "skill". Its id reads <namespace>/skill/<slug> and, like every asset id, is permanent: a new revision changes the record, never the id. The entry needs:

• tier: "core", so the skill is available offline wherever its design system is;
• a license;
• exactly one md format, pointing at SKILL.md. Reference files go in the record, not in formats.

The skill's own fields live in meta.skill:

The Lolly Demo photography entry, with its checksum and size left for the build to fill:

{
  "id": "lolly/skill/photography",
  "name": "Lolly Demo photography",
  "description": "How Lolly Demo photographs look, and how to grade, crop and credit them.",
  "type": "skill",
  "version": "1.0.0",
  "tier": "core",
  "formats": [
    { "format": "md", "url": "/catalog/assets/lolly/skills/photography/SKILL.md", "checksum": "sha256-PLACEHOLDER", "size": 0 }
  ],
  "license": "CC0-1.0",
  "meta": {
    "skill": {
      "name": "lolly-demo-photography",
      "description": "How Lolly Demo photographs look and how to grade, crop and treat them. Use when choosing, editing or grading a photograph for Lolly Demo work, in Darkroom, Filter or Design.",
      "discipline": "photography",
      "audience": "public",
      "status": "draft",
      "skillRevision": "1.0",
      "maintainer": "lolly",
      "appliesTo": { "tools": ["darkroom", "filter"], "families": ["lolly/luts/"] }
    }
  }
}

To add a skill to a brand pack, put SKILL.md and any references/ under catalog/assets/<namespace>/skills/<slug>/, add the entry, then follow the steps in Add an asset to a catalog. pnpm run validate:catalog runs the same admission check the CLI and the MCP server run on every read. It also checks the id pattern, the tier, the licence, the single md format, that no two skills share a name and each reference file's checksum. A skill that fails is refused with the reason. Owner lint warnings, such as a long body or an unclosed code fence, are printed and do not fail the build.

Public and internal skills

audience decides where a skill can travel.

A statically hosted catalog is public whichever profile built the catalog, so internal is enforced by leaving files out of static output, not by hiding them. The CLI and an MCP server on your own machine read the brand pack from your disk, so they serve internal skills too. An MCP server counts as hosted when it sets LOLLY_MCP_HOSTED=1 or NODE_ENV=production, or when its LOLLY_MCP_PUBLIC_ORIGIN is not a local address (localhost, 127.0.0.1 or [::1]). A hosted listing reports how many skills it left out as withheld.

What the coverage map says

lolly system skill coverage <name>, and the MCP file lolly://design-system/skill/{name}/coverage.json, set what a skill says against the design system. Each row has one status:

The map for the Lolly Demo brand skill:

Lolly Demo brand standards (r1.0)

guidance-only  Voice: Not checked: the design system has no text-case rule. One could be drafted in Usage & rules.
agree          Colour: These values are colours in the design system. #09141a #ffffff #033633 #50c369 #fac044 #25c2c2 #7476e0 #da1889
agree          Type: SUSE is a declared font family.
agree          Type: Outfit is a declared font family.
agree          Type: SUSE Mono is a declared font family.
guidance-only  Type: Not checked: the design system has no text-weight rule. One could be drafted in Usage & rules.
guidance-only  Logo: Not checked: Lolly has no rule for logo clear space yet.
guidance-only  Layout: Not checked: the design system has no text-align rule. One could be drafted in Usage & rules.

How to read the map:

• Lines are matched by fixed patterns, outside code samples: hex colours, the font families the tokens declare and words that point at a kind of house rule. No model reads the skill. A row means "this line matched this pattern", never "Lolly understood the guide".
• Lines that match nothing are not in the map. They are still guidance for people and agents to read.
• A checked row says a rule of that kind exists. Read the rule to see whether the rule and the sentence agree.
• Tokens win when Lolly renders. A conflict or not-in-tokens row is for the owner to resolve, in the skill or in the tokens. Lolly changes neither.
• Rows are grouped by section, so a palette of forty swatches makes one or two rows, not forty.

The same report carries the owner lint: missing frontmatter, a long body, a repeated heading, an unclosed code fence, the external sites the skill links to and the scope hints listed under Write a skill Lolly carries well.

A skill is guidance. lolly check, lolly system check and the MCP tool lolly_check apply the house rules. Nothing in the coverage map is a check result, and a map where every row reads agree does not mean Lolly approved the skill or the work made with the skill.

Use a skill with any model

Through Lolly's MCP server

The design brief (lolly://design-context, or lolly system context --json) carries a skills section with the same index and the addresses each skill is read from. In the brief, coverage.skills is declared when the design system has authored skills and generated when only the baseline exists.

An agent reads the index first, then the overall brand skill, then the skill for the discipline at hand. Skills speak for brand intent only. They never grant an agent permissions, tools or access to a document, and the Lolly skill tells agents the same.

In the web app, the Brand Studio (#/start) lists the active design system's skills in a Skills room.

In a folder for a local agent tool

lolly system skill <name> --into=<dir> writes a standard Agent Skills folder that works with no connection to Lolly. Point --into at the directory your agent tool reads skills from.

lolly system skill lolly-demo-photography --into=./skills --origin=https://lolly.tools

skills/lolly-demo-photography/
  SKILL.md
  lolly.json
  references/exemplars-lolly-luts.json

Without --into, the command prints the SKILL.md it would write.

The body of the exported SKILL.md is the brand's text. Lolly changes only link targets, and adds frontmatter when the source has none. lolly.json records the asset, the revision, the SHA-256 of the stored source, the mode, every link target Lolly rewrote and every asset it held back. When appliesTo lists an asset family, the folder also lists an even spread of exemplars from that family in references/. For a family of SVG files, a measured draft profile (viewBoxes, paints and path counts) sits in references/ too, for the owner to review against the skill. A draft profile is a measurement, not a rule.

Linked or bundled

A file that bundled mode leaves out is listed with the reason, as in lolly/logo/primary (licence not recorded), on the command line and under heldBack in lolly.json. --include-licensed copies held-back files anyway, as your own stated choice.

Check that a copy is current

An exported folder is a snapshot. Nothing updates the folder, and it goes out of date when the brand publishes a new revision. Its frontmatter carries these metadata keys:

The generated baseline adds lolly-generated: "true".

lolly system skill check ./skills/lolly-demo-photography

The check compares the copy's SHA-256, or its catalog version when either side lacks a checksum, with the design system's current skill. It answers Up to date: revision 1.0., or gives both revisions when the copy is behind. For a copy with no lolly-asset key, the check reports that Lolly cannot tell where the copy came from.

Limits

• Size. SKILL.md is at most 64 KiB. With its references, a skill stays within 512 KiB, and it has at most 16 references.
• Text only. References are .md, .json, .csv or .txt files directly under references/. No images, no scripts and no other folders. A file that breaks a rule is refused with a reason: Lolly never admits part of a skill or quietly drops a file.
• Lolly does not edit the brand's text. It never rewrites the stored bytes, never fetches an external link and never corrects wording. Lint findings go to the owner.
• The coverage map is narrow. It compares 3- and 6-digit hex values, declared font family names and a short list of statement kinds. A colour written as RGB, CMYK, a Pantone number or a name alone is not compared.
• The CLI and MCP server read the content profile. lolly system skills lists the active content profile's skills, whichever terminal design system is active. Both list appliesTo and leave the choice of skills to the agent.
• Internal skills have no signed-in route yet. A hosted server never serves them, and no server serves them to signed-in callers yet.
• A copy is a snapshot. Freshness metadata helps only when something reads the metadata.

Where to go next

• Tool Skills: guidance for one tool, and agent invitations.
• MCP Server: connecting an agent, and the other resources.
• Brand architectures: how skills behave when brands share work.
• Authoring Assets: the catalog workflow a skill follows.