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

> Explore the Nutlope/hallmark project structure. Understand the root-level organization of skills, site, and docs for an installable AI design skill, live demo, and documentation.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), you'll find the **skill entry point** declared in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) — The demo homepage
- [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) — Compiled token definitions illustrating Hallmark's theming system
- [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) — Lightweight interaction helpers

Run the local demo server with:

```bash
npm run serve

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

```

### docs/ — Documentation and Examples

Human-readable guides live in `docs/`:

- [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) — Worked examples for each Hallmark verb
- [`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md) — Deep-dive case studies
- `docs/screenshots/` — Visual reference of generated outputs

### Configuration Files at Root

| File | Purpose |
|------|---------|
| [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | NPM manifest declaring `"name": "hallmark"`, version, skill entry point, and `serve` script |
| [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md) | Public overview, installation instructions, and demo link |
| `LICENSE` | MIT license |
| [`vercel.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json) → `skill.entry` to locate [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/README.md) and `docs/` provide installation and usage guidance

---

## Working with the Repository

### Install Hallmark as a skill

```bash
npx skills add nutlope/hallmark

```

This command reads [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), copies [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and `references/` into the host assistant's skill directory, and makes the four verbs available.

### Read the skill definition programmatically

```javascript
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

```bash

# 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.