Troubleshooting Common Hallmark Installation Errors: A Complete Guide

Most Hallmark installation failures stem from missing Node.js prerequisites, permission conflicts in npm caches, or the skill files landing in incorrect agent-specific directories.

Hallmark is an AI-powered design auditing skill for Claude Code, Cursor, and Codex that you install via npx. While the npx skills add nutlope/hallmark command simplifies distribution, the cross-platform nature of Node.js and the varying configuration paths for different AI agents introduce specific failure modes. This guide walks through the exact error signatures you will encounter and the precise fixes validated against the Nutlope/hallmark source code.

Prerequisites: Verifying Node.js and npm

Before running the install command, confirm your environment meets the baseline requirements.

Hallmark requires Node.js ≥ 14. Verify your installation:

node -v
npm -v

If either command returns command not found, install Node.js from the official distribution. The npx utility ships with npm, so a missing npx error always indicates Node.js is not on your $PATH.

Resolving "Command Not Found" Errors

The npx: command not found error occurs when the npm CLI is unavailable. This is the most fundamental blocker.

1. Install Node.js from nodejs.org.
2. Restart your terminal to refresh environment variables.
3. Re-run the installation:

npx skills add nutlope/hallmark

Fixing Permission Denied (EACCES) Errors

The npm ERR! code EACCES error indicates the global npm cache or target skill directory is owned by root, preventing writes to user-level paths like ~/.claude/skills/.

Avoid using sudo with npx. Instead, fix directory ownership:

chown -R $USER ~/.npm
chown -R $USER ~/.claude

If you must use sudo due to corporate machine policies, understand that this will install the skill files with root ownership, which may cause runtime read errors when the agent executes under your user context.

Handling Network Timeouts and Registry Issues

Corporate firewalls and proxies frequently block the npm registry, resulting in network timeout or DNS error messages during install.

Force npm to use the public registry and configure your proxy:

npm config set registry https://registry.npmjs.org/
npm config set proxy http://proxy.company.com:8080
npx skills add nutlope/hallmark

Correcting Skill Location Errors

If the install succeeds but Hallmark is unavailable, the skill files likely landed in the wrong directory for your specific agent.

According to the README.md (lines 94-102), Hallmark expects these exact paths:

• Claude Code: ~/.claude/skills/hallmark/
• Cursor: .cursor/rules/hallmark.mdc
• Codex: ~/.codex/skills/hallmark/

Verify the installation manually:

ls ~/.claude/skills/hallmark/

# Expected: SKILL.md  references/  site/  ...

If SKILL.md is missing from the expected location, the agent cannot bootstrap the skill verbs (audit, redesign, study).

Repairing Corrupted Installations

Runtime crashes often indicate incomplete file copies. Hallmark’s architecture depends on three pillars that must exist in the skill directory:

1. Skill definition – skills/hallmark/SKILL.md (contains verb signatures and dependency declarations like framer-motion on line 166)
2. Reference data – skills/hallmark/references/ (holds macrostructure and anti-pattern specifications)
3. UI scaffold – Generated output components

If a verb crashes immediately, reinstall and validate the core files:

npx skills add nutlope/hallmark
cat ~/.claude/skills/hallmark/skills/hallmark/references/verbs/audit.md | head -n 5

# Should output: "# `hallmark audit`"

Resolving Design File Conflicts

Hallmark crashes on first run if your project contains an existing design.md file. Hallmark treats this as a locked design system specification, causing a collision.

Fix: Rename or delete the existing design.md:

mv design.md design.md.backup
hallmark audit ./index.html

Addressing Missing Runtime Dependencies

When Hallmark generates pages referencing libraries like framer-motion, the target project must contain those dependencies.

Install missing packages manually:

npm install framer-motion@11

Check package.json in the Nutlope/hallmark repository for the exact version constraints Hallmark expects.

Verifying the Installation

Run this diagnostic checklist to confirm a healthy install:

1. Check Node version: node -v returns v18.x or higher
2. Validate skill files exist: ls ~/.claude/skills/hallmark/SKILL.md
3. Test a read-only verb: hallmark audit ./site/examples/tally/index.html
4. Confirm output generates a markdown punch-list without file modifications

Summary

• Node.js ≥ 14 is mandatory – npx failures always trace back to missing Node or npm.
• Permission errors require ownership fixes, not sudo – run chown -R $USER ~/.npm to resolve EACCES errors.
• Agent-specific paths matter – Claude Code uses ~/.claude/skills/hallmark/, while Cursor uses .cursor/rules/.
• Three files must survive installation – SKILL.md, the references/ directory, and package.json dependencies must be present for verbs to function.
• Existing design.md files cause crashes – rename them before running Hallmark.

Frequently Asked Questions

Why does Hallmark say "skill not found" immediately after installation?

The skill files were likely copied to the wrong location for your AI agent. Each host uses a different directory: Claude Code expects files in ~/.claude/skills/hallmark/, Cursor looks in .cursor/rules/hallmark.mdc, and Codex uses ~/.codex/skills/hallmark/. Verify the path matches your specific agent and that SKILL.md exists in that directory.

Can I install Hallmark without internet access?

No. The npx skills add command downloads the skill from the npm registry. If you are behind a corporate proxy, configure npm with npm config set proxy before installing. Offline installation is not supported because npx requires registry access to resolve the nutlope/hallmark package.

Why does hallmark audit crash with a "missing framer-motion" error?

Hallmark’s generated code references specific UI libraries declared in skills/hallmark/SKILL.md (line 166). If your target project lacks these dependencies, install them with npm install framer-motion@11. Hallmark does not automatically inject dependencies into your project during the audit phase.

How do I completely remove and reinstall Hallmark?

Delete the skill directory for your agent (e.g., rm -rf ~/.claude/skills/hallmark/) and clear the npm cache with npm cache clean --force. Then re-run npx skills add nutlope/hallmark to perform a fresh installation. This resolves corruption issues in the references/ folder or SKILL.md file.

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