How to Run Hallmark Locally: A Complete Setup Guide for the AI Design Skill

To run Hallmark locally, clone the repository and run npm run serve to start a Python HTTP server on port 4173, then open http://localhost:4173 in your browser.

Hallmark is a static-site-based design skill by @Nutlope that generates polished HTML/CSS designs via AI assistants like Claude Code, Cursor, and Codex. Learning how to run Hallmark locally lets you preview the demo UI, customize themes, and experiment with the skill's reference documents without relying on the hosted version at usehallmark.com.

What You Need to Know About Hallmark's Architecture

Hallmark's repository separates skill definition from web demonstration:

Component	Purpose	Location
Skill files	Markdown references AI assistants read	skills/hallmark/ (entry point: SKILL.md)
Web preview	Self-contained HTML/CSS/JS demo	site/ directory
Local server	Static file serving via Python	package.json defines the serve script

The skill itself requires no runtime — it's plain markdown. Running Hallmark locally means serving the static site/ folder so you can view the design previews in a browser.

Step-by-Step: Run Hallmark Locally

1. Clone the Repository

git clone https://github.com/Nutlope/hallmark.git
cd hallmark

No build tools or dependencies are required. The repository has zero runtime dependencies.

2. Start the Local Server

Run the provided NPM script:

npm run serve

This executes python3 -m http.server --directory site 4173 as defined in package.json. The server:

• Serves only the site/ directory (other files stay inaccessible)
• Runs on port 4173
• Requires no bundler, no build step, no Node.js server

3. Open the Local Preview

Navigate to:

http://localhost:4173

You'll see the same landing page hosted at usehallmark.com. The UI in site/index.html renders Hallmark's design system, and site/js/main.js powers interactions like pressing T to cycle through themes.

4. Make Changes (Optional)

Edit any file in site/ — HTML, CSS, or JavaScript — and refresh your browser. The Python server reads directly from disk, so changes appear instantly without restarting.

Alternative: Install Hallmark as a Skill

If you want Hallmark available to AI assistants without running a local server, install it as a skill:

npx skills add nutlope/hallmark

This copies skills/hallmark/ (including SKILL.md and the references/ library) into each assistant's skill directory. The skill works offline — no server required. AI assistants read the markdown references to generate designs matching Hallmark's macrostructures, typography, and themes.

Key Files When Running Hallmark Locally

File Path	What It Does
package.json	Defines the serve script that launches python3 -m http.server
site/index.html	Main demo page; contains the entry point for Hallmark's UI
site/js/main.js	Client-side script handling theme cycling and navigation
skills/hallmark/SKILL.md	Skill entry point consumed by Claude Code, Cursor, Codex
skills/hallmark/references/	Markdown library covering macrostructures, typography, and themes

Quick Reference: Hallmark Local Commands

Goal	Command
Clone repository	git clone https://github.com/Nutlope/hallmark.git
Install dependencies	npm install (optional — no runtime deps)
Run Hallmark locally	npm run serve
View in browser	http://localhost:4173
Install as skill	npx skills add nutlope/hallmark

Summary

Running Hallmark locally is straightforward because the project is architected as a static site:

• No build step — the site/ folder contains plain HTML, CSS, and JavaScript
• One command — npm run serve starts a Python HTTP server on port 4173
• Instant feedback — refresh the browser to see file changes
• Dual purpose — the same repository works as a local demo and an installable AI skill

Whether you're previewing designs before using the skill or modifying the reference documents, running Hallmark locally gives you full control over the experience.

Frequently Asked Questions

Do I need Node.js or Python installed to run Hallmark locally?

You need Python 3 because npm run serve launches python3 -m http.server. Node.js is only required to execute the NPM wrapper script — the server itself is Python-based. No Node.js runtime dependencies exist in the repository.

Can I use a different port than 4173?

Yes, but you'll need to modify the command. The serve script in package.json hardcodes port 4173. To use another port, run the Python server directly: python3 -m http.server --directory site [YOUR_PORT].

What's the difference between running Hallmark locally and installing it as a skill?

Running locally serves the web demo in site/ so you can view designs in a browser. Installing as a skill copies markdown references from skills/hallmark/ so AI assistants can generate Hallmark-style designs. The two operations are independent — you can do either, both, or neither.

Does Hallmark require internet access once running locally?

No. After cloning, the local server runs entirely offline. The site/ folder contains all assets (HTML, CSS, JS, fonts if any) needed for the demo. The skill references are also local markdown files.

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