How to Build Hallmark from Source: Complete Installation Guide

To build Hallmark from source, clone the Nutlope/hallmark repository, install Node.js dependencies with npm install, optionally run npm run build to bundle assets, and either serve the site/ directory locally or copy it to your AI assistant's skills folder.

Hallmark is a static design skill that lives entirely in HTML, CSS, and JavaScript files. Building Hallmark from source requires only Node.js and a few terminal commands to get the skill running locally or installed for Claude Code, Cursor, or Codex. This guide references the exact file paths and build scripts defined in the repository source code.

Prerequisites

Before you begin, ensure you have:

• Git installed to clone the repository
• Node.js (v16 or later) to run the build process and install dependencies
• A terminal or command prompt

Step-by-Step Build Process

Clone the Repository

Start by cloning the Hallmark repository from GitHub and navigating into the project directory:

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

This downloads the entire project, including the package.json, site/ directory, and skill definitions.

Install Node Dependencies

Run the install command to fetch the development tools and build dependencies specified in package.json:

npm install

This reads the dependency list from [package.json](https://github.com/Nutlope/hallmark/blob/main/package.json) and installs the required packages locally.

Build the Static Assets

Hallmark's HTML and CSS are already static, but the repository includes a build script that bundles JavaScript and copies assets into the site/ folder. To generate a fresh build:

npm run build

This executes the build script defined in the scripts section of package.json.

Serve the Site Locally

To verify the build works, serve the site/ directory using any static file server:

# Using Node.js

npx serve site

# Or using Python

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 the core JavaScript from [site/js/main.js](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).

Install Hallmark for AI Assistants

Once built, copy the static files to your AI assistant's skill directory. The repository places skill definitions in skills/hallmark/, but the built site/ folder contains the deployable assets.

Claude Code

Copy the built site to the Claude Code skills directory:

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

Cursor

For Cursor, copy the skill rules file:

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

Codex

Install for Codex (personal or project scoped):

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

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

Key Source Files

Understanding the repository structure helps when modifying the skill:

• package.json — Defines Node dependencies and the build script used to bundle assets
• site/index.html — The static entry point that loads CSS and initializes the application
• site/js/main.js — Core JavaScript powering interactive features like theme switching and verb handling
• skills/hallmark/SKILL.md — The skill definition consumed by Claude Code, Cursor, and Codex at runtime
• skills/hallmark/references/ — Supporting documentation including verbs, themes, and design guidelines

Summary

• Building Hallmark from source requires only git clone, npm install, and optionally npm run build
• The site/ directory contains the complete static build output ready for deployment
• Installation differs by AI assistant: use ~/.claude/skills/hallmark for Claude Code, ~/.cursor/rules/hallmark.mdc for Cursor, and ~/.codex/skills/hallmark for Codex
• Key files include package.json for build configuration and site/js/main.js for core functionality

Frequently Asked Questions

Do I need to run the build step to use Hallmark?

No. Since Hallmark is a static design skill, the HTML and CSS in the site/ directory work without compilation. Running npm run build is optional and only necessary if you want to bundle JavaScript assets or refresh the build output after making changes to the source.

What if the skill doesn't appear in my AI assistant?

Verify that you copied the files to the correct location according to the README.md installation instructions. For Claude Code, the path is ~/.claude/skills/hallmark. For Cursor, ensure you placed the file in ~/.cursor/rules/. Restart your AI assistant after copying the files to ensure it loads the new skill.

Can I modify the skill behavior?

Yes. Edit the files in the site/ directory, then rebuild using npm run build if you modified JavaScript that requires bundling. The main logic lives in site/js/main.js, while the skill definition for AI assistants is defined in skills/hallmark/SKILL.md.

Is Node.js required just to view the design skill?

No. You can directly open site/index.html in a browser without Node.js. Node is only required to run the build process defined in package.json or to serve the site using npx serve.

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