Visual Representation of the Nutlope/hallmark Directory Structure

The Nutlope/hallmark repository groups its source into three primary folders—site/, skills/hallmark/, and docs/—that separate the static demo, the AI skill definition, and the usage documentation.

The Nutlope/hallmark project is a lightweight design-skill package installable into Claude Code, Cursor, or Codex. Understanding its directory structure lets you quickly locate the static website source, the markdown references that power design verbs, and the recipe guides that demonstrate real-world usage. Below is a complete visual breakdown of the folder hierarchy and an explanation of how each part contributes to the whole.

Visual Overview of the Nutlope/hallmark Directory Structure

The root level keeps metadata minimal. Alongside README.md, LICENSE, and package.json, the repository uses three purpose-built directories to isolate runtime demos from skill logic and human-facing documentation.

.
├── README.md
├── LICENSE
├── package.json
├── site/
│   ├── index.html
│   ├── js/
│   │   └── main.js
│   ├── css/
│   │   ├── base.css
│   │   ├── components.css
│   │   ├── sections.css
│   │   └── tokens.css
│   ├── examples/
│   │   ├── grid-01/
│   │   │   ├── index.html
│   │   │   └── styles.css
│   │   └── custom-02/
│   │       ├── index.html
│   │       ├── styles.css
│   │       └── script.js
│   └── OG-hallmark.png
├── skills/
│   └── hallmark/
│       ├── SKILL.md
│       └── references/
│           ├── verbs/
│           │   ├── audit.md
│           │   └── redesign.md
│           ├── components/
│           │   └── t1-pull-quote-with-marginalia.md
│           ├── genres/
│           │   └── modern-minimal.md
│           └── custom-theme.md
└── docs/
    ├── recipes.md
    ├── study-examples.md
    ├── talk-slides.md
    └── screenshots/
        ├── hero-hum-07.jpg
        └── hero-cobalt-01.jpg

Root-Level Configuration Files

The top-level files provide standard project metadata. package.json contains the minimal npm metadata used by the npx skills add installer, while README.md supplies the project overview and quick-start instructions. LICENSE holds the MIT license text.

site/ — Static Demo Website

The site/ folder powers the live demo at https://www.usehallmark.com. It is a self-contained collection of HTML, CSS, and vanilla JavaScript that showcases generated pages and theme examples. Every page’s macrostructure is encoded as a comment inside its CSS file, starting with site/css/base.css. The site/js/main.js file handles theme switching and UI interactions, while the examples/ subdirectory contains standalone pages such as grid-01/index.html and custom-02/index.html that demonstrate specific layout patterns.

skills/hallmark/ — AI Skill Definitions

This directory is the core intelligence consumed by Claude Code, Cursor, and Codex. skills/hallmark/SKILL.md is the entry point that defines the skill, while the references/ subdirectory organizes markdown guides by category. Verbs live under skills/hallmark/references/verbs/ (e.g., audit.md and redesign.md), component patterns live under skills/hallmark/references/components/ (e.g., t1-pull-quote-with-marginalia.md), and genre guides such as modern-minimal.md live under skills/hallmark/references/genres/. The custom-theme.md file provides the detailed workflow for creating a completely custom design.

docs/ — Documentation and Screenshots

Higher-level guides and visual assets live here. docs/recipes.md provides worked examples that illustrate how to invoke the skill’s verbs. docs/study-examples.md contains sample study-mode inputs and expected DNA extraction outputs. docs/talk-slides.md holds presentation material, and docs/screenshots/ stores hero images such as hero-hum-07.jpg and hero-cobalt-01.jpg used by the live demo.

How site/, skills/, and docs/ Work Together

The repository architecture is deliberately modular. The static demo in site/ visualizes the design system described by the markdown references in skills/hallmark/references/. When you run a command like hallmark audit path/to/project, the tool reads the reference files under skills/hallmark/references/verbs/audit.md to decide which macrostructure, theme, and component patterns to apply. The docs/ folder then provides the human-readable recipes and screenshot assets that explain those outputs to end users.

Practical Commands for Navigating the Repository

Developers typically interact with the project in three ways: installing the skill, running a design verb, or serving the demo locally.

1. Install the skill into Claude Code, Cursor, or Codex

   npx skills add nutlope/hallmark

   This command copies SKILL.md and the references/ markdown files to the appropriate location.

2. Run a verb against a target

   hallmark audit path/to/project
   hallmark redesign path/to/brief
   hallmark study https://example.com

   Each verb reads the reference files under skills/hallmark/references/ to determine the correct design logic.

3. Serve the live demo locally

   npm install -g serve
   serve site

   Opening http://localhost:5000 displays the same pages you see at https://www.usehallmark.com, allowing you to inspect the generated HTML and CSS directly.

Essential Files to Bookmark

If you want to dive straight into the source, these files are the most informative:

• README.md — High-level project description, live-demo link, and installation instructions.
• skills/hallmark/SKILL.md — The core skill definition consumed by AI editors.
• site/index.html — Entry point for the static website.
• site/js/main.js — Powers theme switching and UI interactions.
• site/css/base.css — Contains macrostructure comments and core design tokens.
• skills/hallmark/references/custom-theme.md — Guide for the “Custom NEW” workflow.
• docs/recipes.md — Worked examples illustrating verb invocations.
• docs/study-examples.md — Sample study-mode inputs and expected outputs.

Summary

• The Nutlope/hallmark repository separates its runtime demo, AI skill logic, and human documentation into three top-level directories: site/, skills/hallmark/, and docs/.
• The site/ directory holds the self-contained HTML, CSS, and JavaScript that power the live demo at usehallmark.com.
• The skills/hallmark/ directory supplies SKILL.md and a rich library of categorized markdown references that drive the audit, redesign, and study verbs.
• The docs/ directory contains recipes, study examples, talk slides, and screenshot assets for reference and learning.

Frequently Asked Questions

What is the purpose of the skills/hallmark/ directory?

The skills/hallmark/ directory contains the SKILL.md entry point and the references/ library that Claude Code, Cursor, and Codex read to perform design audits, redesigns, and studies. It functions as the brain of the project, providing the structured guidance that AI agents use to analyze and generate designs.

How do I run the Hallmark demo site on my local machine?

Navigate to the cloned repository and run serve site after installing the serve package globally. This hosts the static files found in site/ at http://localhost:5000, letting you inspect site/index.html, site/css/base.css, and the example pages directly in your browser.

Which file defines the design tokens and macrostructure?

site/css/base.css encodes the macrostructure comments and core design tokens that drive the visual layout of every generated page. The JavaScript in site/js/main.js consumes these tokens to handle theme switching.

Can I use Hallmark without installing it into an AI editor?

Yes. The site/ folder is a self-contained static website; you can open site/index.html directly in a browser or serve it with any static file server without ever touching the AI skill files under skills/hallmark/.

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