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

> Learn how to run Hallmark locally with this complete setup guide. Clone the repository and follow simple steps to get the AI design skill running on your machine.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)) |
| **Web preview** | Self-contained HTML/CSS/JS demo | `site/` directory |
| **Local server** | Static file serving via Python | [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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

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

```bash
npm run serve

```

This executes `python3 -m http.server --directory site 4173` as defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) renders Hallmark's design system, and [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash
npx skills add nutlope/hallmark

```

This copies `skills/hallmark/` (including [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Defines the `serve` script that launches `python3 -m http.server` |
| [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) | Main demo page; contains the entry point for Hallmark's UI |
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Client-side script handling theme cycling and navigation |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.