How to Integrate Hallmark with AI Coding Assistants: Claude Code, Cursor, and Codex Setup

You integrate Hallmark by installing the skill via npx skills add nutlope/hallmark, which deposits SKILL.md and the references/ directory into assistant-specific paths, enabling four design verbs (audit, redesign, study, and build) directly in your chat interface.

Hallmark is a design-system skill for AI coding assistants that prevents "AI slop" by enforcing macrostructure, typography pairing, and token constraints. When you integrate Hallmark with Claude Code, Cursor, or Codex, you gain the ability to audit existing components, redesign pages against a mood board, or study live URLs to extract design DNA.

Hallmark Skill Architecture Overview

The Hallmark repository (Nutlope/hallmark) delivers skills as front-matter-driven rule sets. The architecture consists of four core components that assistants load into their skill registries.

SKILL.md

Located at skills/hallmark/SKILL.md, this file declares the skill metadata (name, description, version) and registers the four verbs that the assistant exposes to users. It also defines safety rails and component-scope flows.

references/ Directory

The skills/hallmark/references/ folder contains the concrete design system: macrostructure templates, token catalogs, anti-pattern lists, and motion rules. These documents are referenced by the verbs during execution.

package.json

The root package.json provides the npx entry point. Running npx skills add nutlope/hallmark fetches the package from the npm registry and extracts the skill files to the correct location for the active assistant.

Demo Assets

The site/_tests/ directory holds self-contained HTML/CSS examples illustrating the 20 catalog themes. These are used by the skill to validate visual output after a build or redesign.

How to Set Up Hallmark for Claude Code

Claude Code scans ~/.claude/skills/ for skill definitions. Hallmark must reside in a subdirectory named hallmark/.

1. Run the installation command from your terminal:

   npx skills add nutlope/hallmark

2. If installing manually, create the directory and copy the files:

   mkdir -p ~/.claude/skills/hallmark
   cp -r skills/hallmark/SKILL.md ~/.claude/skills/hallmark/
   cp -r skills/hallmark/references/ ~/.claude/skills/hallmark/

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

How to Set Up Hallmark for Cursor

Cursor expects skills as single .mdc files inside .cursor/rules/, without front-matter.

1. Install the skill package:

   npx skills add nutlope/hallmark

2. Extract only the body of SKILL.md (excluding the front-matter) into a new file:

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

3. Ensure the .mdc file contains no front-matter; Cursor parses plain MDC syntax only.

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

How to Set Up Hallmark for Codex

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

Personal Installation

npx skills add nutlope/hallmark
cp -r skills/hallmark/SKILL.md ~/.codex/skills/hallmark/
cp -r skills/hallmark/references/ ~/.codex/skills/hallmark/

Project-Scoped Installation

mkdir -p .codex/skills/hallmark
cp skills/hallmark/SKILL.md .codex/skills/hallmark/
cp -r skills/hallmark/references/ .codex/skills/hallmark/

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

Invoking Hallmark Verbs from Your Assistant

Once integrated, you invoke Hallmark through natural language or direct commands in the assistant's chat interface.

Redesign a component with a specific mood:

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

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

Study a live URL to extract design patterns:

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

Hallmark fetches the page, extracts macrostructure, type-pairing, and color anchors, then emits a design.md ready for hand-off.

Audit existing code for anti-patterns:

hallmark audit ./src/components/Hero.tsx

The verb cross-references your code against the anti-pattern lists in skills/hallmark/references/ and reports violations.

Summary

• Skill Format: Hallmark uses a front-matter-driven SKILL.md plus a references/ directory containing design constraints.
• Installation: Run npx skills add nutlope/hallmark to automatically place files in the correct assistant-specific paths.
• Claude Code: Requires SKILL.md and references/ copied to ~/.claude/skills/hallmark/.
• Cursor: Requires a single .mdc file at .cursor/rules/hallmark.mdc with front-matter stripped.
• Codex: Supports both ~/.codex/skills/hallmark/ (personal) and .codex/skills/hallmark/ (project-scoped).
• Verbs: Four callable actions—audit, redesign, study, and the default build—are registered by parsing SKILL.md.

Frequently Asked Questions

What file format does Cursor require for Hallmark skills?

Cursor expects a single .mdc file located at .cursor/rules/hallmark.mdc. Unlike Claude Code or Codex, Cursor cannot parse YAML front-matter. You must extract only the body content from SKILL.md (excluding the front-matter lines) and save it as plain Markdown in the .mdc file.

Can I use the same Hallmark skill files across different AI assistants?

Yes. The skill format is deliberately assistant-agnostic. The underlying rule-set in SKILL.md and the reference documents in references/ remain identical across Claude Code, Cursor, and Codex. Only the destination path and format vary (folder vs. single file, with or without front-matter).

Where are the reference documents stored in the Hallmark repository?

Reference documents are stored in skills/hallmark/references/. This directory contains macrostructure templates, token definitions, typography pairing rules, and anti-pattern lists that the verbs use to enforce design constraints.

How do I update Hallmark to the latest version in my AI assistant?

Re-run npx skills add nutlope/hallmark from your terminal. The command pulls the latest version from the npm registry and overwrites the existing skill files in your assistant's skill directory. Restart the assistant to reload the updated skill registry.

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