How to Install Hallmark for Claude Code, Cursor, and Codex

Run npx skills add nutlope/hallmark once to install Hallmark across Claude Code, Cursor, and Codex—no manual file copying required.

Hallmark is an open-source skill that brings design-system auditing and redesign verbs (audit, redesign, study) to AI coding assistants. This guide walks through installing Hallmark for each supported environment based on the official Nutlope/hallmark repository.

What Hallmark Installs

Hallmark is packaged as a skill—a collection of Markdown files rather than a binary. The core files live in skills/hallmark/ and serve distinct purposes:

• SKILL.md — The skill manifest containing the name, description, version, and command-line invocation rules
• references/ — Directory holding architecture-level rule-sets including macrostructures, token definitions, theme gates, and slop-test configurations

When installed, these files are automatically copied to assistant-specific locations where the AI loads them at runtime.

Installation Command

The unified installer pulls Hallmark from the npm registry and handles all path placement:

npx skills add nutlope/hallmark

This single command detects your environment and writes files to the appropriate destinations. No additional configuration is needed.

Installing Hallmark for Claude Code

Claude Code loads skills from ~/.claude/skills/. After running the installer:

ls ~/.claude/skills/hallmark/

You should see:

SKILL.md
references/

The skill loads automatically on your next Claude Code session. You can immediately use verbs like:

claude "hallmark audit ./src/components"

Installing Hallmark for Cursor

Cursor uses markdown-code rule files placed in .cursor/rules/. The installer extracts the body of SKILL.md (without front-matter) and writes it to:

.cursor/rules/hallmark.mdc

Verify the installation:

cat .cursor/rules/hallmark.mdc

Cursor treats this file as an editor rule-set, making Hallmark verbs available directly in the IDE. Use them in Cursor's chat or command palette.

Installing Hallmark for Codex

Codex supports both personal and project-scoped skill installations:

Scope	Path
Personal	~/.codex/skills/hallmark/
Project	.codex/skills/hallmark/

The installer defaults to personal scope unless run within a project context. Verify installation:

ls ~/.codex/skills/hallmark/

# or for project scope:

ls .codex/skills/hallmark/

Invoke Hallmark in Codex:

codex run "hallmark redesign ./src/theme.css"

File Locations Reference

Assistant	Destination Path	Content
Claude Code	~/.claude/skills/hallmark/	Full skill with SKILL.md and references/
Cursor	.cursor/rules/hallmark.mdc	Body of SKILL.md without front-matter
Codex (personal)	~/.codex/skills/hallmark/	Full skill directory
Codex (project)	.codex/skills/hallmark/	Full skill directory

These paths are defined in the README at lines 100-105 of the repository.

Available Hallmark Verbs

Once installed across any assistant, three core verbs become available:

• hallmark audit <target> — Analyze code against design-system rules
• hallmark redesign <target> — Propose structural improvements using macrostructures and themes
• hallmark study <target> — Deep-dive into component patterns against reference implementations

Each verb consults the references/ rule-sets at runtime to enforce consistent design-system compliance.

Troubleshooting Installation

Skill not loading in Claude Code? Ensure the directory structure matches exactly: ~/.claude/skills/hallmark/SKILL.md must exist, not ~/.claude/skills/SKILL.md.

Cursor rules not appearing? Confirm the file extension is .mdc and located at .cursor/rules/hallmark.mdc within your project root.

Codex cannot find Hallmark? Check that you're using the correct scope—personal ~/.codex/ vs. project .codex/—and that the references/ subdirectory was copied alongside SKILL.md.

Summary

• One command installs all: npx skills add nutlope/hallmark handles every assistant
• Claude Code uses ~/.claude/skills/hallmark/ with automatic loading
• Cursor receives .cursor/rules/hallmark.mdc as a project-local rule file
• Codex supports both ~/.codex/skills/hallmark/ (personal) and .codex/skills/hallmark/ (project)
• Core files SKILL.md and references/ provide the manifest and runtime rule-sets

Frequently Asked Questions

Does Hallmark require npm or Node.js installation?

Yes. The npx skills add command requires Node.js and npm to fetch the package from the registry. However, Hallmark itself contains only Markdown files—no compiled binaries or runtime dependencies.

Can I install Hallmark for multiple assistants simultaneously?

Yes. Running npx skills add nutlope/hallmark detects all supported assistants on your system and installs to each applicable location in a single pass. You do not need to run the command separately per assistant.

How do I update Hallmark to a newer version?

Re-run npx skills add nutlope/hallmark. The installer overwrites existing skill files with the latest version from the npm registry. Your previous installations are replaced atomically—no manual cleanup of old files is necessary.

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