How Hallmark Integrates with AI Coding Assistants: Claude Code, Cursor, and Codex Setup Guide

Hallmark integrates with AI coding assistants as a portable design skill that uses a front-matter-driven rule-set (SKILL.md) and reference documents to expose four core verbs—audit, redesign, study, and build—directly within the assistant's chat interface.

The open-source repository Nutlope/hallmark delivers a design skill architecture that Claude Code, Cursor, and Codex can ingest to generate anti-"AI slop" interfaces. Unlike traditional CLI tools, Hallmark functions as a declarative rule-set that assistants load into their skill registries, allowing you to invoke design system commands from natural language prompts.

Architecture of the Hallmark Skill

Hallmark’s integration relies on a portable skill format that remains assistant-agnostic. The repository structures the skill into three primary components:

• SKILL.md — Located at skills/hallmark/SKILL.md, this file declares the skill metadata (name, description, version) and registers the four verbs that assistants expose to users. It also defines safety rails and component-scope flows.
• references/ — The skills/hallmark/references/ directory holds concrete design constraints, including macro-structure templates, token catalogs, anti-pattern lists, and motion rules that the verbs reference during execution.
• package.json — Provides the npx entry point that fetches the skill from the npm registry when you run the installation command.

When an assistant loads Hallmark, it copies SKILL.md and the entire references/ directory into a scanned skills location. The assistant parses the front-matter, registers the verbs (audit, redesign, study, and the default build), and makes them callable from the chat interface.

Integration Steps for Each Assistant

While the underlying skill files remain identical, each AI coding assistant expects the files in a specific location or format.

Claude Code Setup

Claude Code expects skills as folders containing SKILL.md and supporting assets.

1. Run the installation command:

npx skills add nutlope/hallmark

2. If installing manually, copy the skill files to Claude’s skills directory:

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

3. Restart Claude Code to force a skill reload. The hallmark verbs will now appear in your chat interface.

Cursor Setup

Cursor requires a single .mdc file without front-matter, located in the project’s rules directory.

1. Run the standard installation:

npx skills add nutlope/hallmark

2. Extract only the body content (excluding the front-matter) from SKILL.md and save it to Cursor’s rules path:

tail -n +7 skills/hallmark/SKILL.md > .cursor/rules/hallmark.mdc

3. Ensure the resulting hallmark.mdc file contains no front-matter, as Cursor expects plain MDC format.

4. Reload the workspace; Cursor will surface the hallmark verbs in its chat UI.

Codex Setup

Codex supports both personal (global) and project-scoped skill locations.

1. Install the skill via npm:

npx skills add nutlope/hallmark

2. Copy SKILL.md and the references/ directory into one of the following locations:

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

3. Restart Codex or reload the project to refresh the skill registry.

Installing and Using Hallmark Commands

Once integrated, you invoke Hallmark through natural language or direct command syntax within your assistant’s chat interface.

Installing the Skill

The universal entry point for all assistants is the npx command:

# From any terminal inside the project directory

npx skills add nutlope/hallmark

This pulls the published package, extracts SKILL.md and references/, and drops them in the appropriate location for the active assistant.

Invoking the Redesign Verb

To redesign a component using a specific mood:

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

The assistant parses the command, runs the redesign verb, and returns a new component file plus an 8-state demo wrapper as defined in the component-scope flow within SKILL.md.

Using the Study Verb with a URL

To extract design DNA from a live site:

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

Hallmark fetches the live page, extracts macrostructure, type-pairing, and color anchors, then emits a design.md file ready for hand-off to any AI-assistant-driven build pipeline.

Key Files and Directory Structure

Understanding the repository layout helps when manually configuring or debugging integrations:

File	Purpose	Location
SKILL.md	Core skill definition, verb registry, and safety rails.	skills/hallmark/SKILL.md
references/	Holds macrostructure templates, token catalogs, anti-pattern lists, and design constraints.	skills/hallmark/references/
package.json	Specifies the version and provides the npx installer entry point.	package.json
site/_tests/	Self-contained HTML/CSS examples illustrating the 20 catalog themes for visual verification.	site/_tests/
docs/recipes.md	Usage patterns for redesigning pages and auditing existing sites.	docs/recipes.md

Summary

• Hallmark integrates with AI coding assistants as a design skill rather than a traditional CLI tool, using SKILL.md and the references/ directory.
• The four verbs (audit, redesign, study, build) are registered by the assistant after parsing the skill's front-matter.
• Claude Code loads skills from ~/.claude/skills/hallmark/, while Cursor requires a front-matter-free .mdc file at .cursor/rules/hallmark.mdc, and Codex supports both ~/.codex/skills/hallmark/ and .codex/skills/hallmark/.
• Installation is standardized via npx skills add nutlope/hallmark, but manual copy steps vary by assistant requirements.
• The skill format is assistant-agnostic, ensuring consistent design system behavior across Claude Code, Cursor, and Codex.

Frequently Asked Questions

What makes Hallmark different from other design system tools?

Hallmark is implemented as a skill that AI assistants load into their context, rather than a library you import into code. According to the Nutlope/hallmark source code, it uses SKILL.md to declare verbs and safety rails, allowing assistants to generate designs that respect macro-structures and token definitions without requiring manual configuration files in your project.

Why does Cursor require a different file format than Claude Code?

Cursor expects plain MDC files without YAML front-matter, whereas Claude Code and Codex parse the front-matter in SKILL.md to register skill metadata. When integrating Hallmark with Cursor, you must strip the front-matter (the first six lines) from SKILL.md using a command like tail -n +7 before saving it as .cursor/rules/hallmark.mdc.

Can I use Hallmark with multiple AI assistants in the same project?

Yes. Because the skill format is assistant-agnostic, you can maintain parallel installations: store the full skill in ~/.claude/skills/hallmark/ for Claude Code, maintain a front-matter-free copy in .cursor/rules/hallmark.mdc for Cursor, and place another copy in .codex/skills/hallmark/ for Codex. All instances reference the same underlying rule-set in skills/hallmark/references/, ensuring consistent design constraints across assistants.

What are the four verbs available in Hallmark?

The SKILL.md file defines four primary actions: audit (analyzes existing code for design system compliance), redesign (transforms components using specified moods), study (extracts design DNA from URLs or screenshots), and the default build verb (generates new components following Hallmark constraints). Each verb references the macro-structures and anti-pattern lists stored in the references/ directory.

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