How to Update Hallmark to the Latest Version: The Complete Guide

Run npx skills add nutlope/hallmark to update Hallmark to the latest version, which overwrites your local installation with the current tip of the main branch from the Nutlope/hallmark repository.

Hallmark is distributed as a skill rather than a traditional npm package, meaning you don't update it through npm update. Instead, the npx skills add command fetches the freshest rules directly from the GitHub repository. This guide covers the exact commands and file paths you need to update hallmark to the latest version across Claude Code, Cursor, and Codex environments.

Why Hallmark Uses Skill-Based Distribution

Unlike conventional CLI tools, Hallmark lives inside your AI editor's skill directory as a set of Markdown instructions and reference files. The canonical source files reside in the Nutlope/hallmark repository:

• skills/hallmark/SKILL.md — The core rule-set that drives Hallmark's verbs and pipelines
• skills/hallmark/references/ — The library of themes, macrostructures, and micro-interactions

Because the project uses a version-agnostic distribution model, the update mechanism simply replaces these files with their latest counterparts from the main branch.

The Universal Update Command

The fastest way to update Hallmark is re-running the installation command. This forces a fresh fetch and overwrite of all skill files:

npx skills add nutlope/hallmark

This command executes the following sequence according to the source code:

1. Clones the nutlope/hallmark repository at the current main HEAD
2. Copies the SKILL.md file and the entire references/ directory into your environment's skill path
3. Overwrites any existing Hallmark files, effectively updating them to the newest version

Because the command always pulls the latest commit, you receive the newest themes, macrostructures, and slop-test rules without tracking specific version numbers.

Platform-Specific Update Paths

While the npx command handles most environments automatically, knowing where files land helps with troubleshooting and manual updates.

Claude Code

In Claude Code, Hallmark lives at ~/.claude/skills/hallmark/.

To update, either re-run the universal command or manually copy these items:

• SKILL.md → ~/.claude/skills/hallmark/SKILL.md
• references/ → ~/.claude/skills/hallmark/references/

# Update and copy specifically for Claude Code

npx skills add nutlope/hallmark && \
cp -r $(npm root -g)/nutlope/hallmark/skills/hallmark/* ~/.claude/skills/hallmark/

Cursor

Cursor stores rules at .cursor/rules/hallmark.mdc, which is the body of SKILL.md without YAML frontmatter.

# Update and strip frontmatter for Cursor's .mdc format

npx skills add nutlope/hallmark && \
sed '/^---/,/^---/d' $(npm root -g)/nutlope/hallmark/skills/hallmark/SKILL.md > .cursor/rules/hallmark.mdc

Codex (OpenAI)

Codex supports both personal (~/.codex/skills/hallmark/) and project-scoped (.codex/skills/hallmark/) installations.

# Update project-scoped Codex skill

npx skills add nutlope/hallmark && \
cp -r $(npm root -g)/nutlope/hallmark/skills/hallmark/* .codex/skills/hallmark/

Manual Update Method (Alternative)

If you prefer not to use npx, or if the skills package is unavailable, update manually:

1. Download the latest SKILL.md and references/ folder from the repository using raw URLs or by downloading the zip
2. Replace the old copies in the appropriate directory for your platform (see paths above)
3. Restart your host IDE (Claude Code, Cursor, or Codex) to reload the updated skill files

Verifying Your Update

After updating, confirm success by checking the version stamp in generated output. Hallmark embeds a comment like /* Hallmark · v1.2.0 */ in CSS files it generates, reflecting the version bundled in the current skill files.

You can also verify the installation by examining the site/_tests/ directory in the repository, which contains generated example pages that should match your updated behavior.

Summary

• Run npx skills add nutlope/hallmark to update hallmark to the latest version across all supported editors
• Hallmark installs as a skill (Markdown rules), not an npm package, requiring file replacement rather than semantic versioning
• Key files updated are SKILL.md (core logic) and references/ (design system library)
• Platform paths differ: Claude Code uses ~/.claude/skills/, Cursor uses .cursor/rules/, and Codex uses ~/.codex/skills/ or .codex/skills/
• Manual updates work by copying the two main artifacts from the Nutlope/hallmark repository to your local skill directory

Frequently Asked Questions

Do I need to uninstall Hallmark before updating?

No. The npx skills add command automatically overwrites existing files in your skill directory. The update process is designed to be destructive-replacement: it copies fresh versions from the repository tip and replaces whatever exists locally, so no separate uninstall step is required.

How do I know which version of Hallmark I have installed?

Check the first comment line in any CSS file generated by Hallmark. The tool stamps each build with a version comment like /* Hallmark · v1.2.0 */. If you need the exact commit, compare your local SKILL.md against the main branch on GitHub to see if they match.

Can I pin Hallmark to a specific version instead of using the latest?

The skills CLI and Hallmark's distribution model are version-agnostic by design, always pulling the main branch tip. If you need a specific version, you must manually download that release's SKILL.md and references/ from the GitHub repository at a specific commit hash, then copy them to your skill directory without using the npx command.

Where are the Hallmark skill files stored on my system?

The location depends on your editor. Claude Code stores them at ~/.claude/skills/hallmark/, Cursor at .cursor/rules/hallmark.mdc, and Codex at either ~/.codex/skills/hallmark/ (global) or .codex/skills/hallmark/ (project-specific). These paths hold the SKILL.md file and the references/ subdirectory containing themes and macrostructures.

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