How to Build the Nutlope/hallmark Project: A Complete Setup Guide

Building the Nutlope/hallmark project requires no compilation—simply install the design skill using npx skills add nutlope/hallmark and optionally serve the static demo site with npm run serve to preview the anti-AI-slop UI examples locally.

The Nutlope/hallmark repository is a design skill for AI-coding assistants like Claude Code, Cursor, and Codex. Unlike traditional JavaScript projects that require bundlers or TypeScript compilation, this project ships as a stand-alone npm package containing ready-to-use skill definitions and reference assets.

Step 1: Install the Hallmark Skill

The primary build step involves adding the skill to your AI assistant environment. This copies the rule-set, macrostructures, and theme tokens to the appropriate system directory.

Run the following command in your terminal:

npx skills add nutlope/hallmark

This command automatically detects your environment and installs the skill to the correct location:

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

The installation copies skills/hallmark/SKILL.md (the entry point declaring the verb set and references) and the entire skills/hallmark/references/ directory, which contains the anti-pattern checks, theme tokens, and design guidelines.

Step 2: Preview the Demo Site Locally (Optional)

While not required for building the project, you can serve the static demonstration site to explore the generated UI examples (including Tally, Wayfare, and NAJM) before applying them to your own code.

Execute the serve script defined in package.json:

npm run serve

This launches python3 -m http.server --directory site 4173, hosting the static site/ folder on port 4173. Navigate to http://localhost:4173 in your browser to view the live examples and inspect the CSS tokens in site/css/tokens.css.

Step 3: Run Hallmark Verbs Against Your Code

Once installed, the skill interprets markdown-based logic rather than compiled binaries. Invoke one of the four verbs against a target directory containing HTML/CSS:

hallmark default ./my-project

Available verbs located in skills/hallmark/references/verbs/ include:

• default: Generates a new UI respecting the anti-AI-slop guidelines
• audit: Reviews existing code against the 57 slop-test gates defined in skills/hallmark/references/slop-test.md
• redesign: Refactors existing markup using Hallmark macrostructures
• study: Analyzes reference inputs (documented in docs/study-examples.md)

When you run hallmark default, the system:

1. Selects a macrostructure and theme based on your brief
2. Applies the theme token set from site/css/tokens.css
3. Runs the 57 slop-test gates to enforce design quality
4. Outputs production-ready HTML and CSS

Understanding the Project Structure

These key files drive the build-less architecture:

• skills/hallmark/SKILL.md: Declares the verb set, references folder, and harnesses for the AI assistant
• skills/hallmark/references/: Contains all design rules, macrostructures, themes, and anti-pattern checks
• site/: Static demo content including index.html and example pages
• package.json: Contains the "serve": "python3 -m http.server --directory site 4173" script for local preview
• docs/recipes.md: Worked-out usage examples for implementing the four verbs

Summary

Building the Nutlope/hallmark project involves environment setup rather than traditional compilation:

• The project requires no bundler or TypeScript compilation—all source files are ready-to-use markdown and static assets
• Install the skill globally using npx skills add nutlope/hallmark to copy definitions to ~/.claude/skills/hallmark/ (or equivalent paths for Cursor/Codex)
• Preview the static demo site locally by running npm run serve, which executes python3 -m http.server on port 4173
• Execute verbs (default, audit, redesign, study) against your target directories to apply the design rule-set and 57 slop-test gates

Frequently Asked Questions

Does the Nutlope/hallmark project require Node.js compilation?

No. This project contains no build step, bundler configuration, or TypeScript compilation. The package.json exists solely to define the serve script for previewing the static demo site. The skill logic resides in markdown files within skills/hallmark/references/ that AI assistants interpret directly.

Where does the npx skills add command install the files?

The command installs files to platform-specific directories: ~/.claude/skills/hallmark/ for Claude Code, .cursor/rules/hallmark.mdc for Cursor, and ~/.codex/skills/hallmark/ for Codex. It copies both SKILL.md and the references/ directory containing the design tokens and slop-test gates.

How do I run the Hallmark slop-test gates locally?

The 57 slop-test gates defined in skills/hallmark/references/slop-test.md execute automatically when you run the audit or default verbs against your target directory. These gates evaluate your HTML/CSS for anti-AI-slop patterns and return compliance reports without requiring a separate build command.

Can I contribute to the project without setting up a build environment?

Yes. Since hallmark requires no compilation, you can edit the markdown reference files (such as skills/hallmark/SKILL.md or files in docs/recipes.md) directly and test changes by reinstalling the skill via npx skills add nutlope/hallmark. The static demo site in site/ can be served immediately using any HTTP server or the provided npm run serve command.

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