How to Install Hallmark for AI Coding Assistants: Complete Setup Guide

Install Hallmark with a single npx skills add nutlope/hallmark command, then copy the skill files to your assistant's designated directory.

Hallmark is an open-source design skill that brings systematic design thinking to AI coding assistants. According to the Nutlope/hallmark source code, it installs as a portable skill package containing a main definition file (SKILL.md) and reference documentation. This guide covers the complete installation process for Claude Code, Cursor, and Codex.

---

Prerequisites

Before installing Hallmark for AI coding assistants, ensure you have:

• Node.js installed (for npx command execution)
• Access to at least one supported AI assistant (Claude Code, Cursor, or Codex)

The installation relies on npx, which fetches the latest Hallmark version (currently v1.1.0) directly from the npm registry without requiring a global package install.

---

Core Installation Command

All assistant setups begin with the same command:

npx skills add nutlope/hallmark

This command downloads the skill package from the npm registry. After execution, you'll find the skill files in your working directory under skills/hallmark/, including:

• [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) — the main skill definition with verb tables and usage notes
• references/ — supporting documentation for macrostructures, themes, and slop-test rules

---

Assistant-Specific Setup

Claude Code

Claude Code requires copying the full skill directory to its global skills location.

Step 1: Run the core installation command.

Step 2: Create the destination directory and copy all files:

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

The references/ directory must be included—Claude Code reads these files at runtime when executing Hallmark verbs (audit, redesign, study, or the default design flow).

Cursor

Cursor uses rule files (.mdc) rather than directory-based skills, and requires stripping YAML front-matter from SKILL.md.

Step 1: Run the core installation command.

Step 2: Create the rule file with front-matter removed:

mkdir -p .cursor/rules
cat skills/hallmark/SKILL.md | sed '1,3d' > .cursor/rules/hallmark.mdc

The sed '1,3d' operation removes the first three lines (typically --- delimited front-matter). Paste only the body of SKILL.md—Cursor's rule engine parses the verb definitions directly from this content.

Codex

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

Step 1: Run the core installation command.

Step 2: Choose your scope and copy files accordingly:

# Personal install (available across all projects)

mkdir -p ~/.codex/skills/hallmark
cp -R skills/hallmark/* ~/.codex/skills/hallmark/

# OR project-scoped install (version-controlled, team-shared)

mkdir -p .codex/skills/hallmark
cp -R skills/hallmark/* .codex/skills/hallmark/

Project-scoped installations are recommended for teams wanting consistent Hallmark behavior across contributors. Personal installs suit individual workflows.

---

Verifying Your Installation

After completing the steps above, test Hallmark by invoking one of its verbs in your assistant. For example, in Claude Code or Codex:

> hallmark audit

The skill should respond with its audit workflow, referencing files from the references/ directory. If you receive "command not found" or missing file errors, verify that:

1. The SKILL.md file exists in the target directory
2. The references/ subdirectory is fully copied (not empty)
3. File permissions allow read access

---

Key Files and Their Roles

File	Location	Purpose
SKILL.md	skills/hallmark/	Main skill definition; contains verb table, version metadata, and structured usage notes
references/	skills/hallmark/references/	Runtime documentation including macrostructures, theme definitions, and slop-test rules
site/css/tokens.css	Repository root	Token stylesheet that Hallmark populates when applying themes
site/index.html	Repository root	Live demo page demonstrating a complete Hallmark build
docs/recipes.md	Repository root	End-to-end usage examples in human-readable format

The references/ directory is essential—Hallmark reads these files dynamically rather than embedding their content in SKILL.md. Omitting this directory causes runtime failures.

---

Summary

• One command installs everywhere: npx skills add nutlope/hallmark fetches the latest version from npm
• Claude Code uses ~/.claude/skills/hallmark/ with full directory copy
• Cursor requires .cursor/rules/hallmark.mdc with front-matter stripped
• Codex offers ~/.codex/skills/hallmark/ (personal) or .codex/skills/hallmark/ (project-scoped)
• Always include the references/ directory—it's required at runtime

---

Frequently Asked Questions

What Node.js version is required to run the npx installation command?

Any Node.js version with npx bundled (Node 8.2.0+) works. The command executes without installing Hallmark globally, so version conflicts are minimal.

Can I install Hallmark on multiple assistants simultaneously?

Yes. Run npx skills add nutlope/hallmark once, then copy the resulting skills/hallmark/ files to each assistant's location as documented above. The same skill package serves all three assistants.

Why does Cursor require stripping front-matter from SKILL.md?

Cursor's .mdc rule parser treats YAML front-matter as configuration rather than content. The sed command removes the --- delimited header so Cursor reads the verb definitions and instructions correctly.

Where are the Hallmark verbs defined?

The verb table—audit, redesign, study, and the default design flow—is structured in [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). Each verb maps to specific interaction patterns documented in the references/ files.

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