How to Integrate Hallmark AI with AI Coding Assistants: A Complete Guide

Integrate Hallmark AI with AI coding assistants by installing the skill via npx skills add nutlope/hallmark, then copying SKILL.md and the references/ folder to the assistant-specific directory—~/.claude/skills/hallmark/ for Claude Code, .cursor/rules/hallmark.mdc for Cursor, or ~/.codex/skills/hallmark/ for Codex.

Hallmark is a design skill for AI coding assistants that enforces strict anti-slop rules and structured UI generation. Available in the Nutlope/hallmark repository, it adds four top-level verbs to Claude Code, Cursor, and Codex, enabling AI-generated interfaces that pass a 58-gate validation suite.

Installation Steps for Each Assistant

The integration process follows a standard pattern: install the skill globally, then copy the manifest and reference files to the assistant's designated skill directory.

Run the global installation first:

npx skills add nutlope/hallmark

This command pulls the package and caches the skill files. You must then manually copy the required files to your target assistant's configuration directory.

Claude Code Setup

For Claude Code, create the skill directory and copy both the manifest and reference library:

mkdir -p ~/.claude/skills/hallmark
cp -r ~/.npm/_npx/*/node_modules/hallmark/skills/hallmark/* ~/.claude/skills/hallmark/

Ensure the references/ folder containing macrostructures, themes, and anti-patterns is fully copied alongside SKILL.md.

Cursor Setup

Cursor uses a single .mdc rule file located at .cursor/rules/hallmark.mdc. Copy the contents of SKILL.md without frontmatter into this file:

cat ~/.claude/skills/hallmark/SKILL.md | tail -n +2 > .cursor/rules/hallmark.mdc

Codex Setup

Codex supports both personal and project-level skills. Copy the same files as Claude Code to either location:

• Personal: ~/.codex/skills/hallmark/
• Project: .codex/skills/hallmark/

Understanding the Skill Architecture

Hallmark operates through a self-contained directory structure (skills/hallmark/) discovered by assistants via the skill manifest. The architecture separates concerns between orchestration logic and design reference data.

The Skill Manifest (SKILL.md)

Located at skills/hallmark/SKILL.md, the manifest defines the skill metadata, available verbs, and implementation safety rails that prevent destructive edits. It specifies the four primary commands—hallmark, hallmark audit, hallmark redesign, and hallmark study—and describes the runtime flow from pre-flight scan to final output validation.

Reference Library Structure

The skills/hallmark/references/ directory contains modular markdown files that the skill loads selectively based on the current task:

• genres/ – Defines four genre presets: editorial, modern-minimal, atmospheric, and playful.
• macrostructures/ – Contains 21 named page-shape definitions (e.g., Marquee Hero), each specifying layout, hero, and component archetype picks.
• components/ – Individual UI component recipes for navs, footers, and hero enrichment.
• custom-theme.md – Logic for tuned and bespoke custom themes when catalog options are insufficient.
• slop-test.md – 58 validation gates that automatically check generated output for design anti-patterns.

Runtime Execution Flow

When you invoke a Hallmark verb, the assistant executes an eight-step pipeline defined in SKILL.md:

1. Pre-flight Scan – Analyzes package.json, tailwind.config.*, existing CSS tokens, and any design.md to infer the current stack.
2. Genre Detection – Selects one of four genres based on brief keywords.
3. Macrostructure Selection – Chooses from 21 macrostructures while respecting diversification rules tracked in .hallmark/log.json.
4. Theme Routing – Defaults to the catalog of 20 named themes, switching to custom palette logic when signaled.
5. Enrichment Decision – Conditionally loads hero enrichment based on brief requirements.
6. Preview Generation – Emits a markdown summary of the planned output before code generation.
7. Slop-Test – Runs 58 validation gates; failures trigger automatic revision passes.
8. Stamp & Log – Prepends a CSS comment with macrostructure, theme, and axes data, then logs the entry to .hallmark/log.json.

Using Hallmark Verbs

Once integrated, Hallmark exposes four top-level verbs that function as natural language commands within your AI assistant chat or CLI.

Building New UI (hallmark)

The default hallmark verb generates fresh interfaces from a brief. Trigger it by typing:

> hallmark

The assistant prompts for audience, use-case, and tone, then executes the full pipeline. It selects a macrostructure (e.g., Marquee Hero), chooses a theme from the 20-theme catalog (e.g., Bloom), and generates HTML and CSS files prefixed with a Hallmark stamp comment containing metadata about the selected axes.

Auditing Existing Code (hallmark audit)

Score existing components against anti-pattern rules without modifying files:

hallmark audit ./src/components/Button.tsx

This command reads the target file, evaluates it against references/anti-patterns.md, and returns a ranked punch list of violations.

Redesigning Pages (hallmark redesign)

Preserve content and structure while replacing the visual layer:

hallmark redesign ./index.html --mood modern-minimal

Hallmark reads the existing markup, maintains routes, tokens, and copy, then applies a new macrostructure and theme while respecting diversification rules to avoid repetition of recently used patterns.

Studying Live Sites (hallmark study)

Extract design DNA from live pages or screenshots:

hallmark study https://www.usehallmark.com/examples/hyperlane/

Hallmark fetches the page and returns a design.md-style report containing the detected macrostructure, palette, and typography. You can then reference this DNA to generate matching interfaces in subsequent builds.

Summary

• Installation requires running npx skills add nutlope/hallmark and copying SKILL.md plus the references/ folder to assistant-specific directories (~/.claude/skills/hallmark/, .cursor/rules/hallmark.mdc, or ~/.codex/skills/hallmark/).
• Architecture centers on skills/hallmark/SKILL.md as the manifest and skills/hallmark/references/ as the modular design library containing 21 macrostructures, 4 genres, and 58 slop-test gates.
• Four verbs provide complete UI workflows: hallmark (build), hallmark audit (validate), hallmark redesign (re-skin), and hallmark study (extract DNA).
• Quality assurance is enforced through an automatic 58-gate slop-test that validates output before delivery and logs selections to .hallmark/log.json for diversification tracking.

Frequently Asked Questions

What files need to be copied for Claude Code integration?

You must copy SKILL.md and the entire references/ folder to ~/.claude/skills/hallmark/. The references/ directory contains critical subfolders including genres/, macrostructures/, components/, and validation rules that the skill dynamically loads during runtime.

How does Hallmark prevent repetitive design patterns?

Hallmark maintains a diversification log at .hallmark/log.json that tracks recently used macrostructures, themes, and enrichment choices. During the Macrostructure Selection step, the skill consults this log to select alternatives, ensuring consecutive runs produce visually distinct outputs unless explicitly overridden.

Can I use Hallmark with custom themes instead of catalog themes?

Yes. While Hallmark defaults to a catalog of 20 named themes defined in the reference library, it routes to references/custom-theme.md when the brief signals custom requirements. This logic supports both tuned variants of catalog themes and fully bespoke palettes defined by specific color values.

What is the slop-test and when does it run?

The slop-test is a 58-gate validator defined in references/slop-test.md that executes automatically after code generation. It checks the output for design anti-patterns, structural inconsistencies, and Hallmark discipline violations. Any failure triggers an automatic revision pass before the final output is presented to the user.

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