Brand Skill Builder
This skill helps you build and maintain a brand skill library: a set of small skills that let any model produce on-brand work for one company. It carries the architecture, templates, scripts and lessons from a production library; it carries no brand of its own. Every brand value comes from the user's sources.
Read references/architecture.md before starting any mode. Read the other references when the step below names them.
Folders. In every command, SKILL_DIR is the folder holding this file and LIB is the library folder the user chooses.
Write both out in full in every command; do not set them as shell variables (on some platforms a variable set in one
command is gone in the next).
Choose the mode
| The user wants | Mode |
|---|---|
| Brand skills for a brand that has none yet | A. New library |
| One more skill in an existing library | B. Add a skill |
| A review of an existing brand skill or library | C. Review |
| To understand the approach before building | Explain from references/architecture.md and stop |
Ask which mode only if the request does not say.
A. New library
- Gather sources. Ask for the brand book and anything that rules on the brand: the design team's templates, a voice guide, a messaging document, trademark rules, a style guide, the logo files, the fonts and their licences, any icon or photo library. Ask who owns the brand (the people who will ratify decisions). Note what is missing; do not fill it in.
- Scaffold.
python3 SKILL_DIR/scripts/scaffold.py library LIB --brand "<Brand>" --era <era>. The era is a short label for this version of the brand (for example2027-brand). Put the sources inLIB/reference/. - Write the foundations in
LIB/shared-context/brand-foundations/context/from the sources, followingreferences/brand-foundations.md. Fill every TODO from a source or record it as a gap. Measure contrast; quote the book's wording where it carries a rule; give every file its provenance. Add logo artwork underlogo/, andlogo-policy.md,imagery-policy.mdandchart-palette.jsonwhen the sources cover them. - Review with the owner. Show the foundations as a short summary: the colour model, the type roles, the signature elements, the ship check, the gaps, and each proposed house decision with one recommendation and its reason. Wait for their decisions; record each in the House decisions table and the dev log.
- Build the voice skill (mode B with
--kind voice). It is small and proves the snapshot, preflight and packaging path. - Build the first format skill (mode B with
--kind format), the format people need most. Smallest end-to-end path first, then pilot loops. - Add formats one at a time, settling each format's house decisions first (
references/process.md, "Order of work"). - Build the audit skill (mode B with
--kind audit) once there are format specs to audit against.
B. Add a skill
- Name it
<brand>-<format>(lowercase, hyphens), or<brand>-voice,<brand>-audit. Confirm one skill, one job: if the request overlaps an existing skill, say so and recommend extending that skill instead. - Scaffold.
python3 SKILL_DIR/scripts/scaffold.py skill LIB <name> --kind format|voice|audit --format "<PDF>". This writes the SKILL.md template,agents/openai.yaml, the preflight, the platform test, and the snapshot configLIB/tools/snapshot/<name>.json; for a format skill alsoLIB/shared-context/<name>/context/format-spec.mdandformat-map.json. - Settle the format's house decisions before writing code: for every decision in
structural-system.mdscoped "others decide when built", recommend an answer for this format, get the owner's decision, record it. - Write the format spec and map (words with BOOK, RATIFIED and PROPOSED tags; numbers with role names, never hex).
- Write the builder and QA scripts following
references/format-skills.md: the model plans and writes a JSON spec, a script builds, a script gates the finished file; tokens read at build time; deviations recorded, never refusals. Voice and audit skills followreferences/voice-and-audit.mdinstead. - Fill SKILL.md: the description (triggers, what it will not do, under 1,024 characters), the steps, the intake with its look-to-spec table, the spec reference, the warn-never-refuse section, and one delivery line per platform.
- Snapshot and verify.
python3 LIB/tools/snapshot/snapshot.py LIB/tools/snapshot/<name>.json, then--check, thenpython3 LIB/skills/<name>/scripts/verify_context.py. Add fonts, stylesheets and artwork tobundled_assetsin the config so the preflight proves them. - Test (
references/qa-and-testing.md): the platform test, fixture builds on both themes, a tamper test per QA check, the token-swap test. Then pilot loops with a realistic prompt, rerunning the same prompt after each fix. - Package when asked (
references/packaging.md):python3 LIB/tools/package/package_skill.py LIB/skills/<name> <name> <fresh scratch folder>/<name>.zip --date YYYY-MM-DD. Unpack into another fresh folder and run the tests from there before placing the zip inLIB/finalized-skills/. - Log it. Every step above goes in
LIB/DEV-LOG.mdas it happens.
C. Review
Read the skill (or library) and compare it with the pattern. Report, in this order, each with the file and line:
- Structure: one job, no runtime calls to other skills,
agents/openai.yaml, no single-platform paths. - Context: a bundled snapshot with a manifest and digests, a preflight that warns rather than stops, a brand era.
- Builder: tokens read at build time (or hard-coded values), a JSON spec, deviations instead of refusals.
- QA: a gate on the finished file mapped to the ship check, tamper tests, a restyle mode if it restyles.
- Workflow: intake with defaults, plan with claim and evidence, approval before build, delivery that leads with warnings.
- Packaging: strict frontmatter, description length and triggers, a release record.
Recommend the fixes in order of impact. Change nothing unless asked.
Rules for every mode
- Never invent brand values. No colour, font, size, rule, claim, figure or customer comes from general knowledge. A gap is recorded and decided by the owner, or the element is left out.
- The brand book is the rule of record; the owners' design files fill its silences; every departure is a house decision with its scope, the book's words it departs from, its status and who decided.
- Warn, never refuse, inside the skills you build: repair and report, deliver failing files labelled, stop only for a physical impossibility. The voice skill with no voice file is that impossibility.
- Recommend, then ask on every choice that belongs to the owner. Build only after they decide.
- Measure, do not guess: contrast, text widths, line counts, renders.
- Look at the output in the real renderer before calling anything done.
Delivery
- on Claude: summarise what was created or changed with paths, and share any packaged zip from the output folder.
- on ChatGPT: summarise what was created or changed with paths, and link any packaged zip as a download.
Then list what is still TODO, each gap waiting on the owner, and each PROPOSED decision.
Reference
| File | Read it for |
|---|---|
references/architecture.md | Skill types, the workspace, the skill folder, snapshot-first context, platform neutrality |
references/brand-foundations.md | Turning a brand book into data: files, colour and type architecture, house decisions, status tags |
references/format-skills.md | The workflow inside a format skill, warn-never-refuse, the spec, the builder, the QA gate, per-format notes |
references/voice-and-audit.md | The voice skill and the audit skill |
references/qa-and-testing.md | Tests, renders, pilots, debugging rules that interact |
references/packaging.md | Strict frontmatter, the description, release steps, upload failures |
references/process.md | Decisions, the living record, order of work, working safely, Office toolchain lessons |