# Troubleshooting Common Hallmark Installation Errors: A Complete Guide

> Fix common Hallmark installation errors. Resolve Node.js issues, npm cache conflicts, and incorrect skill file paths with this comprehensive troubleshooting guide for the Nutlope/hallmark repository.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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:

```bash
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](https://nodejs.org).
2. Restart your terminal to refresh environment variables.
3. Re-run the installation:

```bash
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:

```bash
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:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash
ls ~/.claude/skills/hallmark/

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

```

If [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/design.md) file. Hallmark treats this as a locked design system specification, causing a collision.

**Fix:** Rename or delete the existing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md):

```bash
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:

```bash
npm install framer-motion@11

```

Check [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md), the `references/` directory, and [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) dependencies must be present for verbs to function.
- **Existing [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) file.