How to Build Hallmark from Source: A Complete Setup Guide

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:

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

The repository root contains README.md, 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), 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:

npm install

This command reads [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:

npm run build

The build script is defined in 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:

# 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), which loads stylesheets and [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

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

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

Cursor

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

Cursor uses .mdc rule files stored in ~/.cursor/rules/. The site/_tests/ directory contains test files and rule definitions formatted for Cursor's system.

Codex

# 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).

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) 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)	Project overview and installation instructions
[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)	Static entry point, loads CSS and JS
[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)	Skill metadata for AI assistant consumption
skills/hallmark/references/	Supporting documentation on design patterns

The skill definition in 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

# 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: 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) 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), 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), handling user interactions like theme selection. Reference documentation in skills/hallmark/references/ provides design guidelines that assistants consult at runtime.

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