# How to Integrate Hallmark with AI Coding Assistants: Claude Code, Cursor, and Codex Setup > Integrate Hallmark with AI coding assistants Claude Code Cursor and Codex using simple setup. Control design with audit redesign study and build verbs directly in your chat. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: how-to-guide - Published: 2026-07-18 --- **You integrate Hallmark by installing the skill via `npx skills add nutlope/hallmark`, which deposits [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](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 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`](https://github.com/Nutlope/hallmark/blob/main/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: ```bash npx skills add nutlope/hallmark ``` 2. If installing manually, create the directory and copy the files: ```bash 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: ```bash npx skills add nutlope/hallmark ``` 2. Extract only the body of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (excluding the front-matter) into a new file: ```bash 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 ```bash 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 ```bash 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: ```text 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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md). **Study** a live URL to extract design patterns: ```text hallmark study https://www.usehallmark.com/examples/wayfare/ ``` Hallmark fetches the page, extracts macrostructure, type-pairing, and color anchors, then emits a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) ready for hand-off. **Audit** existing code for anti-patterns: ```text 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.