# How to Integrate Hallmark AI with AI Coding Assistants: A Complete Guide > Integrate Hallmark AI with AI coding assistants easily. Follow our complete guide to install the skill and connect with Claude Code, Cursor, or Codex for enhanced coding. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: how-to-guide - Published: 2026-07-25 --- **Integrate Hallmark AI with AI coding assistants by installing the skill via `npx skills add nutlope/hallmark`, then copying [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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: ```bash 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: ```bash 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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md). ### Cursor Setup Cursor uses a single `.mdc` rule file located at `.cursor/rules/hallmark.mdc`. Copy the contents of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) **without** frontmatter into this file: ```bash 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md)** – Logic for tuned and bespoke custom themes when catalog options are insufficient. - **[`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md): 1. **Pre-flight Scan** – Analyzes [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, existing CSS tokens, and any [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/.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: ```plaintext > 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: ```bash hallmark audit ./src/components/Button.tsx ``` This command reads the target file, evaluates it against [`references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/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: ```bash 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: ```bash hallmark study https://www.usehallmark.com/examples/hyperlane/ ``` Hallmark fetches the page and returns a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) for diversification tracking. ## Frequently Asked Questions ### What files need to be copied for Claude Code integration? You must copy [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.