How to Document Skills for Nutlope/hallmark: The Complete Developer Guide

Documenting skills for Nutlope/hallmark requires creating a self-contained markdown-based skill definition under the skills/ directory, consisting of a SKILL.md manifest, a references/ corpus with indexed rule-sets, and verb-specific implementation files that define executable workflows for AI coding agents.

The Nutlope/hallmark repository implements a modular skill system that plugs into Claude Code, Cursor, and Codex. Properly documenting these skills ensures AI agents can discover, interpret, and execute design workflows consistently across different harnesses. This guide covers the exact file structure, metadata schemas, and maintenance procedures used to document the Hallmark design skill.

Understanding the Skill Architecture

The Skill Manifest

Every skill begins with SKILL.md, located at skills/hallmark/SKILL.md. This file serves as the entry point and declares the skill's metadata using a front-matter schema containing name, description, and version fields. The body of the manifest provides a human-readable overview of the four executable verbs (audit, redesign, study, and the default build) and describes the design workflow. When a harness loads the skill, it reads this file to discover the entry point and the location of the reference corpus.

The Reference Corpus

The skills/hallmark/references/ directory contains the complete rule-set that governs the skill's behavior. This corpus is loaded on demand by the skill runtime and includes:

• Macrostructures — 21 named page shapes (e.g., Marquee Hero, Stat-Led) defined in macrostructures.md, which enforces the diversification rule preventing consecutive runs from using the same macrostructure.
• Themes — 20 catalog themes (e.g., Hum, Cobalt) with colour-band, display-style, and accent-hue metadata stored in site/css/tokens.css.
• Anti-patterns — A list of design tells that the skill must refuse, such as gradient heroes and centred layouts, documented in anti-patterns.md.
• Genres — Four genre files (editorial.md, modern-minimal.md, atmospheric.md, playful.md) that scope tone and theme rotation.

Verb Implementations

Each executable command has its own markdown file under skills/hallmark/references/verbs/. The skill runtime parses the user brief, selects the appropriate verb file (audit.md, redesign.md, or study.md), and follows the step-by-step flow described within. These files contain the explicit logic for pre-flight scans, token preservation, and output generation.

Core Documentation Components

Macrostructures and Theme Indexes

The macrostructure index at skills/hallmark/references/macrostructures.md maintains the canonical list of 21 layout patterns and enforces the diversification rule. When documenting new macrostructures, you must update this index to include the new entry while preserving alphabetical order.

Theme documentation lives in site/css/tokens.css, which stores the required --dot, --dot-edge, and --num custom properties. These CSS variables enable the theme picker UI to render the palette correctly and allow the skill to select themes based on brief signals and diversification rules.

Anti-Patterns and Quality Gates

The skills/hallmark/references/anti-patterns.md file catalogs design tells that the skill must refuse. These rules feed into the slop-test gate, which runs 58 gated checks after code generation. The test logic itself resides in skills/hallmark/references/slop-test.md, ensuring outputs contain no invented metrics, use locked tokens, and implement mobile-ready breakpoints.

Genre and Voice Definitions

Genre files located in skills/hallmark/references/genres/ define the tonal boundaries for each design mode. Each file scopes the allowable theme rotations and voice characteristics, ensuring the skill maintains consistency when executing verbs under specific genre constraints.

Step-by-Step Guide to Documenting Skills

When adding new macrostructures, themes, or verbs to Nutlope/hallmark, follow this documentation workflow:

1. Create a markdown file in the appropriate subfolder (references/macrostructures/ or references/themes/). Use existing files as templates to maintain the same heading hierarchy and comment stamps.

2. Update the index (macrostructures.md or themes.md) to include the new entry, preserving alphabetical or numeric order as established in the existing corpus.

3. Add CSS tokens to site/css/tokens.css with the required --dot, --dot-edge, and --num custom properties so the theme picker UI can render the new palette.

4. Run the slop-test locally via the site's serve script to ensure new artifacts pass all 58 gates. Failures are reported and must be fixed before the skill returns final output.

5. Commit changes with a descriptive message, such as "Add 'Chronicle' macrostructure and update index".

Working with the Hallmark CLI

The documented skill supports several CLI workflows through the hallmark command. The package descriptor in package.json declares the skill as an npm package and lists supported harnesses (claude-code, cursor, codex).

Install the skill using:

npx skills add nutlope/hallmark

Execute the default build verb:

hallmark build "Design a landing page for a coffee subscription service"

Extract design DNA from existing sites:

hallmark study https://example.com/awesome-landing

Audit existing pages without modification:

hallmark audit ./src/pages/about.html

Redesign pages while preserving brand assets:

hallmark redesign ./src/pages/home.html --mood modern-minimal

Before any generation, Hallmark performs a pre-flight scan that examines the host project's package.json, tailwind.config.*, and existing tokens.css. The findings are emitted as a stamped comment and cached in .hallmark/preflight.json to preserve existing design tokens and framework choices.

Summary

• Skill metadata lives in skills/hallmark/SKILL.md, which declares the skill name, version, and available verbs for harness discovery.
• Reference documentation resides in skills/hallmark/references/, containing indexed macrostructures, themes, anti-patterns, and genre definitions that govern output quality.
• Verb workflows are documented in skills/hallmark/references/verbs/ as markdown files that the runtime parses to execute audit, redesign, and study commands.
• Quality assurance depends on anti-patterns.md and slop-test.md, which implement 58 gated checks to prevent design anti-patterns in generated code.
• Theme system requires synchronized updates to site/css/tokens.css and the theme index to maintain the diversification rule and proper UI rendering.

Frequently Asked Questions

How do I add a new macrostructure to the Hallmark skill?

Create a new markdown file in skills/hallmark/references/macrostructures/ using existing files as templates, then update skills/hallmark/references/macrostructures.md to include the new entry while preserving alphabetical order. Ensure the new macrostructure adheres to the diversification rule that prevents consecutive runs from using the same layout shape.

What is the slop-test and how does it work?

The slop-test is a quality gate implemented in skills/hallmark/references/slop-test.md that runs 58 checks after code generation. It verifies that outputs contain no invented metrics, use locked design tokens, and implement mobile-ready breakpoints. The test references anti-patterns.md to score output quality and automatically fixes failures before returning the final result.

How does the skill handle theme diversification?

The skill selects themes based on brief signals and a diversification rule stored in the reference corpus. Theme metadata including colour-band, display-style, and accent-hue lives in site/css/tokens.css with specific --dot, --dot-edge, and --num custom properties. The system prevents consecutive runs from using the same theme by checking the diversification index.

Where are the executable verb workflows defined?

Verb implementations are documented as markdown files in skills/hallmark/references/verbs/, specifically audit.md, redesign.md, and study.md. The skill runtime parses these files to discover the step-by-step flow for each command, including pre-flight scanning, token preservation, and the slop-test validation sequence.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}