Nutlope/hallmark Project Structure: A Complete Guide to the Root-Level Organization

The Nutlope/hallmark repository is organized into four core directories—skills/, site/, docs/, and configuration files—that together define an installable AI design skill, a live demo site, and comprehensive documentation.

The Hallmark project is a self-contained design skill for AI-coding assistants like Claude Code, Cursor, and Codex. The root-level structure follows a clean separation between skill metadata, runtime assets, documentation, and deployment configuration. Understanding how the Nutlope/hallmark project is structured at the root level helps developers install, extend, and contribute to this open-source design system.

---

The Four Core Directories

skills/ — Skill Definition and Design Library

The skills/ directory contains the heart of the Hallmark system: the skill definition that AI assistants consume and the extensive reference library that drives design decisions.

In skills/hallmark/SKILL.md, you'll find the skill entry point declared in package.json via "skill.entry": "skills/hallmark/SKILL.md". This file defines:

• Skill front-matter and metadata
• The four Hallmark verbs: audit, redesign, study, and the default build
• Safety rails and design flow rules

Adjacent to SKILL.md, the skills/hallmark/references/ subdirectory houses the design knowledge base:

• Macrostructures — page layout patterns and compositional frameworks
• Themes — visual design systems and token definitions
• Genres — content type classifications
• Anti-patterns — design mistakes to avoid
• Slop-test — quality control criteria

site/ — Live Demo and Static Showcase

The site/ directory powers https://www.usehallmark.com, the public-facing demonstration of Hallmark-generated pages.

Key contents include:

• site/index.html — The demo homepage
• site/css/tokens.css — Compiled token definitions illustrating Hallmark's theming system
• site/js/main.js — Lightweight interaction helpers

Run the local demo server with:

npm run serve

# Executes: python3 -m http.server --directory site 4173

docs/ — Documentation and Examples

Human-readable guides live in docs/:

• docs/recipes.md — Worked examples for each Hallmark verb
• docs/study-examples.md — Deep-dive case studies
• docs/screenshots/ — Visual reference of generated outputs

Configuration Files at Root

File	Purpose
package.json	NPM manifest declaring "name": "hallmark", version, skill entry point, and serve script
README.md	Public overview, installation instructions, and demo link
LICENSE	MIT license
vercel.json	Deployment configuration for Vercel hosting
.gitignore	Git exclusions

---

Complete Root-Level Layout

nutlope/hallmark/
├── docs/                 # Markdown documentation & screenshots

├── site/                 # Live demo (HTML, CSS, JS)

│   ├── css/
│   │   └── tokens.css    # Token-based theming system

│   ├── js/
│   │   └── main.js
│   └── index.html        # Demo homepage

├── skills/               # Skill definition & reference library

│   └── hallmark/
│       ├── SKILL.md      # Skill entry point (declared in package.json)

│       └── references/   # Macrostructures, themes, genres, anti-patterns

├── .gitignore
├── LICENSE
├── package.json          # NPM manifest and skill metadata

├── README.md             # Project overview

└── vercel.json           # Deployment config

---

How the Components Connect

The Nutlope/hallmark project structure at the root level creates three interconnected systems:

1. Skill consumption — AI assistants read package.json → skill.entry to locate skills/hallmark/SKILL.md and its reference library
2. Visual demonstration — The site/ directory compiles to a browsable showcase of Hallmark capabilities
3. Developer onboarding — README.md and docs/ provide installation and usage guidance

---

Working with the Repository

Install Hallmark as a skill

npx skills add nutlope/hallmark

This command reads package.json, copies SKILL.md and references/ into the host assistant's skill directory, and makes the four verbs available.

Read the skill definition programmatically

import fs from 'fs';

// Access the skill front-matter used by Claude Code, Cursor, Codex
const skill = fs.readFileSync('skills/hallmark/SKILL.md', 'utf8');
console.log(skill.split('\n').slice(0, 10).join('\n'));

Access reference materials

# List available design references

ls skills/hallmark/references/

# Typical output: anti-patterns.md  genres.md  macrostructures.md  themes.md ...

---

Summary

• skills/hallmark/ contains the skill definition (SKILL.md) and reference library that power Hallmark's design intelligence
• site/ hosts the static demo at usehallmark.com with token-based CSS theming
• docs/ provides human-readable recipes, examples, and screenshots
• package.json declares the skill entry point and provides a local server script
• The root structure enables installation into AI assistants, live demonstration, and straightforward contribution

---

Frequently Asked Questions

What is the purpose of the skills/hallmark/SKILL.md file?

skills/hallmark/SKILL.md is the entry point for the Hallmark skill system. AI assistants like Claude Code, Cursor, and Codex read this file to understand the four verbs (audit, redesign, study, build), safety rails, and design flow. It is referenced in package.json via the "skill.entry" field, allowing automated installation via npx skills add.

How does the site/ directory relate to the rest of the project?

The site/ directory is a compiled static showcase that demonstrates Hallmark-generated pages in a browser. It operates independently from the skill system but uses the same token-based theming defined in site/css/tokens.css. The demo site is deployed to https://www.usehallmark.com and can be run locally with npm run serve.

Can I use Hallmark without the demo site or documentation?

Yes. The minimal requirement is the skills/hallmark/ directory containing SKILL.md and its references/ folder. The site/ and docs/ directories are optional for skill functionality but recommended for understanding and showcasing Hallmark's capabilities. When installing via npx skills add nutlope/hallmark, only the skill definition is copied to your AI assistant.

What files should I modify to extend Hallmark's design capabilities?

Extend Hallmark by adding to skills/hallmark/references/. New macrostructures, themes, or anti-patterns added here become available to the skill's reasoning engine. Modify SKILL.md only to add new verbs or change core behavior. The site/ and docs/ directories are for demonstration and should be updated to reflect new capabilities.

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