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

Run npx skills add nutlope/hallmark to install Hallmark across Claude Code, Cursor, and Codex, which automatically copies the skill manifest and reference rules to assistant-specific directories.

Hallmark is an open-source design system skill published by Nutlope that adds structured auditing and redesign capabilities to AI coding assistants. Installing Hallmark requires executing a single npm command that distributes the skill files to ~/.claude/skills/hallmark/, .cursor/rules/hallmark.mdc, or ~/.codex/skills/hallmark/ depending on your target environment. This guide provides the exact installation steps and file locations based on the source code in the Nutlope/hallmark repository.

What Is Hallmark?

Hallmark is delivered as a skill—a collection of Markdown files that describe a design system and a set of verbs for AI-coding assistants. According to the source code, the core definition lives in skills/hallmark/SKILL.md, which contains the skill manifest (name, description, version) and command-line invocation rules. The skills/hallmark/references/ directory houses the architecture-level rule-sets, macro-structures, token definitions, and slop-test gates that Hallmark enforces at runtime.

Installation Command

The entire installation process is handled by the skills CLI. The repository's package.json declares the package used by the installer.

Open a terminal and run:

npx skills add nutlope/hallmark

This command pulls the skill from the npm registry and writes the necessary files to the correct locations for each assistant. No manual copying is required.

Assistant-Specific Setup Paths

Each AI assistant loads skills from a specific directory structure. After running the installer, the files are placed as follows:

Claude Code Installation

For Claude Code, the installer copies the skill directory to:

~/.claude/skills/hallmark/

This path contains SKILL.md and the references/ folder. Claude Code loads the skill automatically on the next session. Once loaded, you can invoke Hallmark verbs directly in the chat interface.

Verify the installation:

ls ~/.claude/skills/hallmark/

# Output: SKILL.md  references/ ...

Cursor Installation

For Cursor, the installer creates a single rule file at:

.cursor/rules/hallmark.mdc

Cursor treats this file as a markdown-code rule set. The installer extracts the body of SKILL.md (removing YAML front-matter) and writes it to the .mdc file, making the Hallmark verbs available within the editor.

Inspect the generated rule:

cat .cursor/rules/hallmark.mdc

Codex Installation

For Codex, Hallmark supports both personal (global) and project-scoped installations:

• Personal: ~/.codex/skills/hallmark/
• Project-scoped: .codex/skills/hallmark/ (within your project root)

Codex reads the skill files from either location, exposing the same verbs defined in SKILL.md. Use the personal path for system-wide availability or the project path for repository-specific enforcement.

Using Hallmark After Installation

Once the command completes, the skill is ready for immediate use. Hallmark provides three primary verbs:

• audit – Analyze existing code against design system rules
• redesign – Refactor components to match Hallmark standards
• study – Learn from reference implementations

Example usage in Codex:

codex run "hallmark audit ./src/components/Button.tsx"

In Claude Code, invoke the verb directly in your prompt:

hallmark redesign ./src/components/Card.tsx

Summary

• Hallmark installs via npx skills add nutlope/hallmark, pulling from the npm registry and distributing files automatically.
• Claude Code loads the full skill directory from ~/.claude/skills/hallmark/ and auto-detects it on startup.
• Cursor consumes a single .cursor/rules/hallmark.mdc file containing the processed body of SKILL.md without front-matter.
• Codex supports both ~/.codex/skills/hallmark/ (personal) and .codex/skills/hallmark/ (project) installation scopes.
• The skill exposes three verbs—audit, redesign, and study—for enforcing design system rules at runtime.

Frequently Asked Questions

Do I need to restart my AI assistant after installing Hallmark?

No restart is required for Claude Code and Codex; the skill loads automatically on the next session or command invocation. For Cursor, the .mdc file is read dynamically by the editor, so the verbs become available immediately after the installation command finishes.

Can I install Hallmark for a single project only?

Yes. While Claude Code installs skills globally to ~/.claude/skills/, Codex supports project-scoped installation at .codex/skills/hallmark/. For Cursor, placing .cursor/rules/hallmark.mdc within your repository makes the skill available only for that specific project.

What is the difference between SKILL.md and the references folder?

SKILL.md serves as the skill manifest located at skills/hallmark/SKILL.md, containing metadata, version information, and verb definitions. The references/ folder contains the actual rule-sets, macro-structures, and slop-test gates that Hallmark applies during audit or redesign operations to evaluate code quality against the design system.

Why does Cursor use a .mdc file instead of the full skill directory?

Cursor's architecture requires markdown-code rules to be stored as individual .mdc files without YAML front-matter. The installer automatically extracts the functional body of SKILL.md and writes it to .cursor/rules/hallmark.mdc, providing the same verb capabilities (audit, redesign, study) while conforming to Cursor's single-file rule format.

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