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

> Discover how Hallmark integrates with AI coding assistants like Claude Code, Cursor, and Codex. This guide explains setup and usage for advanced code generation and review.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-20

---

**Hallmark integrates with AI coding assistants as a portable design skill that uses a front-matter-driven rule-set ([`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)** — Located at [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and supporting assets.

1. Run the installation command:

```bash
npx skills add nutlope/hallmark

```

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

```bash
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:

```bash
npx skills add nutlope/hallmark

```

2. Extract only the body content (excluding the front-matter) from [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and save it to Cursor’s rules path:

```bash
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:

```bash
npx skills add nutlope/hallmark

```

2. Copy [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash

# From any terminal inside the project directory

npx skills add nutlope/hallmark

```

This pulls the published package, extracts [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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:

```text
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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md).

### Using the Study Verb with a URL

To extract design DNA from a live site:

```text
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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)** | Core skill definition, verb registry, and safety rails. | [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) |
| **`references/`** | Holds macrostructure templates, token catalogs, anti-pattern lists, and design constraints. | `skills/hallmark/references/` |
| **[`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)** | Specifies the version and provides the `npx` installer entry point. | [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) |
| **`site/_tests/`** | Self-contained HTML/CSS examples illustrating the 20 catalog themes for visual verification. | `site/_tests/` |
| **[`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md)** | Usage patterns for redesigning pages and auditing existing sites. | [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) |

## Summary

- Hallmark integrates with AI coding assistants as a **design skill** rather than a traditional CLI tool, using [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) to register skill metadata. When integrating Hallmark with Cursor, you must strip the front-matter (the first six lines) from [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.