# How to Build Hallmark from Source: A Complete Setup Guide

> Learn how to build Hallmark from source. Follow this guide to clone the repo, install dependencies, and serve the static site for your project. Get started now.

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

---

**To build Hallmark from source, clone the GitHub repository, install Node.js dependencies, optionally run the build script, and serve or copy the static `site/` directory to your target environment.**

Hallmark is a static design skill distributed entirely through HTML, CSS, and JavaScript files. According to the Nutlope/hallmark source code, the project requires no complex compilation pipeline—just standard Node.js tooling to manage dependencies and an optional build step. This guide walks through every stage with direct references to the actual source files.

## Prerequisites

Before you begin, ensure you have:

- **Git** installed for cloning the repository
- **Node.js** (version 16 or higher recommended) for dependency management
- A terminal with bash, zsh, or equivalent shell access

Hallmark's core files live in the `site/` directory and are fully static, so production deployment only requires a web server or file copy operation.

## Step 1: Clone the Repository

Start by cloning the Hallmark repository and entering the project directory:

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

```

The repository root contains [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md), [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), and the `site/` directory that holds all static assets. As documented in [[`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md)](https://github.com/Nutlope/hallmark/blob/main/README.md), this is a zero-configuration static site designed for portability across AI assistant platforms.

## Step 2: Install Node.js Dependencies

Install the project's development dependencies:

```bash
npm install

```

This command reads [[`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)](https://github.com/Nutlope/hallmark/blob/main/package.json) to fetch build tools and any JavaScript bundlers required by the project. The dependency footprint is minimal since Hallmark ships as pre-built static files.

## Step 3: Build the Static Assets (Optional)

Hallmark's HTML and CSS are already production-ready in the repository. However, if you want a fresh build or are modifying the source, run:

```bash
npm run build

```

The **build script** is defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) under the `"scripts"` section. It bundles JavaScript assets and copies files into the `site/` folder. For most users, the pre-built files in `site/` are sufficient.

## Step 4: Serve the Site Locally

To verify your build or develop locally, serve the `site/` directory:

```bash

# Using npx serve (installed with npm)

npx serve site

# Or using Python's built-in HTTP server

python -m http.server --directory site 8000

```

The entry point is [[`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)](https://github.com/Nutlope/hallmark/blob/main/site/index.html), which loads stylesheets and [[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)—the core JavaScript handling theme switching, verb interactions, and other dynamic features. Visit `http://localhost:3000` (or your chosen port) to test.

## Step 5: Install the Skill for Your AI Assistant

Hallmark integrates with Claude Code, Cursor, and Codex. Copy the appropriate files based on your target platform:

### Claude Code

```bash
cp -r site ~/.claude/skills/hallmark

```

This installs the skill to Claude Code's default skills location, making it available across all projects.

### Cursor

```bash
cp site/_tests/* ~/.cursor/rules/hallmark.mdc

```

Cursor uses `.mdc` rule files stored in `~/.cursor/rules/`. The [`site/_tests/`](https://github.com/Nutlope/hallmark/blob/main/site/_tests/) directory contains test files and rule definitions formatted for Cursor's system.

### Codex

```bash

# Personal scope (global)

cp -r site ~/.codex/skills/hallmark

# Or for project-scoped installation, copy to your project's root

cp -r site ./.codex/skills/hallmark

```

Codex supports both personal and project-scoped skills. The installation logic follows the same pattern: static files are copied to a known location where the assistant can reference them.

All installation paths are documented in the **Install** section of [[`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md)](https://github.com/Nutlope/hallmark/blob/main/README.md).

## Step 6: Verify the Installation

Confirm your setup by:

1. **Web verification**: Visit `http://localhost:8000` (or your chosen port) and ensure the page renders without console errors
2. **JavaScript verification**: Open browser DevTools and confirm [[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) loads and executes—check for functional theme toggles or verb selectors
3. **AI assistant verification**: Open Claude Code, Cursor, or Codex and invoke Hallmark through your assistant's skill system

## Key Source Files and Their Roles

| File | Purpose |
|------|---------|
| [[`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md)](https://github.com/Nutlope/hallmark/blob/main/README.md) | Project overview and installation instructions |
| [[`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)](https://github.com/Nutlope/hallmark/blob/main/package.json) | Dependency list and build script definitions |
| [[`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)](https://github.com/Nutlope/hallmark/blob/main/site/index.html) | Static entry point, loads CSS and JS |
| [[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Core interactivity: themes, verbs, UI state |
| [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Skill metadata for AI assistant consumption |
| [`skills/hallmark/references/`](https://github.com/Nutlope/hallmark/tree/main/skills/hallmark/references) | Supporting documentation on design patterns |

The skill definition in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and the reference materials in `references/` are consumed at runtime by Claude Code, Cursor, and Codex to provide contextual design assistance.

## Build Commands Reference

```bash

# Full setup from scratch

git clone https://github.com/Nutlope/hallmark.git
cd hallmark
npm install
npm run build

# Local development server

npx serve site

# Platform-specific installation

cp -r site ~/.claude/skills/hallmark        # Claude Code

cp site/_tests/* ~/.cursor/rules/hallmark.mdc  # Cursor

cp -r site ~/.codex/skills/hallmark         # Codex

```

## Summary

- **Hallmark requires no compilation**: The `site/` directory contains complete, static HTML/CSS/JS files ready for deployment
- **Node.js is optional but recommended**: Use `npm install` and `npm run build` only if modifying source files or wanting a fresh build
- **Installation is file-copy simple**: Copy the `site/` directory to platform-specific locations for Claude Code (`~/.claude/skills/`), Cursor (`~/.cursor/rules/`), or Codex (`~/.codex/skills/`)
- **Local testing requires any static server**: The Python one-liner or `npx serve` both work identically
- **Core logic lives in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)**: Theme switching, verb handling, and all interactivity are implemented here

## Frequently Asked Questions

### Does Hallmark require a build step to use?

No. Hallmark ships with pre-built static files in the `site/` directory. You can copy these directly to your AI assistant's skills folder without running any commands. The build step is only necessary if you modify source files or want to verify the build pipeline works.

### What Node.js version does Hallmark require?

The project uses standard npm features without exotic dependencies. Node.js 16 or higher is recommended based on common compatibility patterns, though [[`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)](https://github.com/Nutlope/hallmark/blob/main/package.json) does not specify an explicit engine constraint.

### Can I use Hallmark without installing it as a skill?

Yes. The `site/` directory is a complete static website. Serve it with any HTTP server and use it as a standalone design reference. The skill packaging simply makes it discoverable by AI assistants; the content is identical.

### Where is the skill's behavior defined?

The **skill metadata** is in [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which describes capabilities to AI assistants. The **interactive behavior** is implemented in [[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), handling user interactions like theme selection. Reference documentation in [`skills/hallmark/references/`](https://github.com/Nutlope/hallmark/tree/main/skills/hallmark/references) provides design guidelines that assistants consult at runtime.