How to Troubleshoot Hallmark Runtime Errors: A Complete Diagnostic Guide

Most Hallmark runtime errors stem from incorrect skill installation, missing reference files, or invalid command syntax, and can be resolved by verifying file paths in the host's skill directory, checking reference names against the repository, and ensuring Node.js 14+ is installed.

Hallmark is a design skill that runs inside Claude Code, Cursor, or Codex to audit and redesign web interfaces. When you encounter hallmark runtime errors, the issue typically traces back to one of three architectural layers: the Markdown skill definition in SKILL.md, the static reference library in references/, or the client-side JavaScript renderer in site/js/main.js. This guide provides precise diagnostics using the actual source code from the Nutlope/hallmark repository.

Verify Skill Installation and File Placement

Installation errors occur when the host LLM cannot locate the skill files or when the front-matter metadata is malformed.

Check Directory Structure by Host

Each AI coding environment expects Hallmark files in a specific location. Verify your installation matches your host:

• Claude Code: ~/.claude/skills/hallmark/
• Cursor: .cursor/rules/hallmark.mdc
• Codex: ~/.codex/skills/hallmark/ (or project-scoped)

If these directories are missing or empty, reinstall the skill:

npx skills add nutlope/hallmark

This command copies SKILL.md and the entire references/ tree into the host's skill directory. Missing files trigger errors like "cannot find …/SKILL.md" or "reference not found".

Validate Front-Matter Syntax

Each copied file must begin with a valid front-matter block. Open SKILL.md or any file in the skill directory and confirm it starts with exactly:

---
applyTo: '**'
---

An invalid front-matter block prevents the host from loading the skill entirely, causing silent failures or parser errors at runtime.

Validate Command Syntax and Arguments

Command-syntax errors happen when you omit required arguments or provide malformed paths to the hallmark CLI.

Required Arguments for Each Verb

Hallmark exposes three primary verbs, each with mandatory targets:

# Score an existing codebase (no edits)

hallmark audit ./my-project

# Redesign a page while preserving copy/IA/brand

hallmark redesign ./my-page.html

# Extract DNA from a screenshot or URL

hallmark study https://example.com/hero

Omitting the target argument emits "Missing required argument ". Supplying a non-existent path returns "ENOENT: no such file or directory".

Inspect the Reference Library

Reference-lookup failures occur when Hallmark cannot find static assets describing macro-structures, typography, motion, or genres.

Resolve "Reference Not Found" Errors

If the error message reads "Reference not found: macrostructures/…", perform these checks:

1. Open the referenced file in the repository, such as skills/hallmark/references/macrostructures.md.
2. Confirm the file is not empty and that heading names match the identifiers used in your command.
3. Verify the reference name is spelled exactly as it appears in the references/genres/ folder (e.g., modern-minimal not modern-minmal).

The error trace typically points to load.js:42 in the stack trace, indicating the exact line where the lookup failed.

Verify Custom Theme Configuration

If using a custom theme, ensure custom-theme.md exists in the references/ directory and that the macro-structure comment inside your generated HTML matches an entry defined in that file.

Parse Error Output and Stack Traces

Hallmark prints concise stack traces that identify the offending layer. Examine the file path shown in the error:

Error: Reference not found: genres/modern-minimal
    at loadReference (/path/to/hallmark/.../load.js:42:15)

Cross-reference this path with the repository structure. If the file was renamed or moved, update the call site in your command or restore the original file from the repository.

Enable Debug Mode for Deep Diagnostics

For cryptic failures, run the audit command with the --debug flag to print a diagnostic dump:

hallmark audit ./my-project --debug

The debug output reveals:

• Loaded skill files and their timestamps
• Resolved reference paths
• Front-matter parsing warnings

Scan this output to pinpoint exactly which layer—skill definition, reference lookup, or renderer—triggered the failure.

Validate the JavaScript Runtime Environment

Client-side JavaScript problems arise when running the live demo or local previews, typically from outdated Node versions or corrupted builds in site/js/main.js.

Node Version Requirements

Verify your environment meets the minimum version:

node --version   # Hallmark requires Node ≥14

Rebuild Static Assets

If the browser console shows "Uncaught SyntaxError" or "Cannot read property 'classList' of undefined", the CSS tokens in the built assets have likely drifted from the HTML markup. Rebuild the static files:

npm install       # Installs dev dependencies

npm run build     # Rebuilds assets from site/js/main.js

This regenerates the client-side renderer that drives the live demo and applies the slop-test gates.

Reinstall the Skill as a Last Resort

If corruption persists across multiple files, wipe the skill directory and perform a clean installation:

# Remove existing copy (adjust path for your host)

rm -rf ~/.claude/skills/hallmark

# Re-install

npx skills add nutlope/hallmark

Because Hallmark consists of pure Markdown and static assets, a fresh copy guarantees no corrupted files remain from previous partial downloads.

Summary

• Verify installation paths for Claude Code (~/.claude/skills/hallmark/), Cursor (.cursor/rules/hallmark.mdc), or Codex (~/.codex/skills/hallmark/).
• Validate command syntax by including required target arguments for audit, redesign, and study verbs.
• Check reference files in skills/hallmark/references/ when encountering "Reference not found" errors.
• Use --debug to expose loaded files, resolved paths, and front-matter warnings.
• Ensure Node.js ≥14 and run npm run build to fix client-side JavaScript errors in site/js/main.js.

Frequently Asked Questions

What causes "Reference not found" errors in Hallmark?

This error occurs when Hallmark cannot locate a file in the references/ directory, such as macrostructures.md or a genre definition in references/genres/. Verify the file exists in the repository, check for exact spelling matches, and ensure the file is not empty. The stack trace typically points to load.js:42 where the lookup failed.

How do I fix front-matter parsing errors?

Front-matter errors happen when SKILL.md or reference files lack the required YAML header. Open the offending file and confirm it begins with ---\napplyTo: '**'\n---. Any syntax deviation, such as missing delimiters or incorrect indentation, prevents the host LLM from loading the skill.

Where does Hallmark store its skill files?

The storage location depends on your AI coding environment. Claude Code uses ~/.claude/skills/hallmark/, Cursor stores rules at .cursor/rules/hallmark.mdc, and Codex uses ~/.codex/skills/hallmark/. If these directories are missing or contain corrupted files, reinstall with npx skills add nutlope/hallmark.

Why does Hallmark report JavaScript errors in the browser?

Client-side errors like "Cannot read property 'classList' of undefined" indicate a mismatch between the built CSS tokens and HTML markup in the demo. Ensure you are running Node.js 14 or higher, then execute npm install and npm run build to regenerate the assets in site/js/main.js.

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