# Main Directories in the Nutlope/hallmark Repository: A Complete Guide

> Explore the Nutlope/hallmark repository's main directories: skills/hallmark for skill logic, site for the demo, and docs for documentation. Understand the structure for efficient development.

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

---

**The Nutlope/hallmark repository contains three top-level directories—`skills/hallmark`, `site`, and `docs`—that separate the core skill logic, runnable demo site, and human-readable documentation.**

The **hallmark** repository is a design-skill ecosystem built to power AI-assisted design audits and redesigns. Understanding its directory structure is essential for anyone who wants to install the skill, extend its capabilities, or study its implementation. This guide breaks down each main directory with specific file paths and practical commands you can run immediately.

## The Three Core Directories

Every project in the hallmark repository falls into one of three self-contained modules. Each serves a distinct purpose in the skill's lifecycle—from definition to demonstration to documentation.

### skills/hallmark — The Skill Definition

The **`skills/hallmark`** directory is the heart of the system. It contains everything the AI needs to perform design-related tasks, packaged as a portable skill.

Key contents include:

- **[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)** — The skill manifest that declares the skill name, version, and **verb implementations**: `audit`, `redesign`, and `study`
- **`references/`** — A subfolder with genre specifications, macrostructures, color systems, typography rules, and anti-pattern catalogs

This directory is what gets installed when you run `npx skills add nutlope/hallmark`. The runtime reads [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) to discover available commands and loads reference files as needed for context.

```bash

# View the skill's declared capabilities

cat skills/hallmark/SKILL.md | grep -E 'audit|redesign|study'

```

### site — The Runnable Demo

The **`site`** directory hosts the public demonstration at **https://www.usehallmark.com**. It contains the static assets, runtime code, and a library of fully-rendered examples.

Structure breakdown:

- **[`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html)** — Root entry point for the demo site
- **`js/`** — Runtime scripts that power the interactive UI
- **`css/`** — Token definitions and style systems
- **`examples/`** — Self-contained pages like `cobalt-01/` and `custom-04/`, each with their own token files and rendered output

Every example in `site/examples/` is a complete, standalone page demonstrating a specific macrostructure and theme combination.

```bash

# Launch a specific example in your default browser

open site/examples/cobalt-01/index.html

```

### docs — Human-Readable Guides

The **`docs`** directory contains explanatory content that is **not required for runtime** but essential for developers and designers who want to understand or extend the skill.

Notable files:

- **[`recipes.md`](https://github.com/Nutlope/hallmark/blob/main/recipes.md)** — Practical "how-to" workflows for common tasks
- **[`talk-slides.md`](https://github.com/Nutlope/hallmark/blob/main/talk-slides.md)** — Presentation materials explaining the skill's architecture
- **[`study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/study-examples.md)** — Walkthroughs of how to analyze existing designs
- **`screenshots/`** — Visual documentation of theme outputs

## Key Files Across All Directories

| File | Location | Purpose |
|------|----------|---------|
| [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md) | Root | Project overview, live demo URL, quick start |
| [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) | `skills/hallmark/` | Skill manifest with verbs and rules |
| [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html) | `site/` | Demo site root |
| [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Root | Dependencies (framer-motion, tailwind) and build scripts |
| [`recipes.md`](https://github.com/Nutlope/hallmark/blob/main/recipes.md) | `docs/` | Practical usage recipes |

## Programmatic Directory Exploration

You can inspect the main directories programmatically. Here is a Node.js snippet that lists the contents of each top-level folder:

```javascript
const fs = require('fs');
const path = require('path');

const dirs = ['skills/hallmark', 'site', 'docs'];

dirs.forEach(dir => {
  console.log(`${dir}:`);
  console.log(fs.readdirSync(path.join(__dirname, dir)).join('\n'));
  console.log('---');
});

```

## Summary

- **`skills/hallmark`** — Implements the skill behavior; contains [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and reference specifications
- **`site`** — Demonstrates the output; hosts the live demo and example library
- **`docs`** — Explains intent and usage; includes recipes, slides, and study guides

These three directories form the complete hallmark ecosystem: installable skill, runnable showcase, and comprehensive documentation.

## Frequently Asked Questions

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

The `skills/hallmark` directory contains the **skill definition** that AI assistants use to perform design tasks. According to the Nutlope/hallmark source code, it includes the [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) manifest file and a `references/` subfolder with rules for genre, color, typography, and macrostructures. This is the only directory required for the skill to function.

### How do I run the demo site locally?

Navigate to the `site` directory and open [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) in a browser, or serve it via a local HTTP server. The `site/examples/` folder contains standalone pages like [`cobalt-01/index.html`](https://github.com/Nutlope/hallmark/blob/main/cobalt-01/index.html) that you can open directly with `open site/examples/cobalt-01/index.html` on macOS or equivalent commands on other platforms.

### What is the difference between `docs` and `skills/hallmark`?

The **`docs`** directory contains human-readable guides, recipes, and slide decks for learning and reference. The **`skills/hallmark`** directory contains machine-readable specifications that the AI runtime consumes. The skill can operate without `docs`, but developers need `docs` to understand how to use it effectively.

### Where are the design tokens and themes defined?

Design tokens and themes live in multiple places. The **`site/css/`** folder contains runtime token definitions used by the demo. The **`skills/hallmark/references/`** folder contains the canonical specifications that the skill uses when generating or auditing designs. Individual examples in `site/examples/` override these with their own token files.