# How to Navigate the Root Directory of the Nutlope/hallmark Repository Effectively

> Effectively navigate the Nutlope/hallmark repository root. Use skills/, site/, and docs/ directories. Discover SKILL.md as your central entry point to the Hallmark design system.

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

---

**Use the `skills/`, `site/`, and `docs/` directories as your primary landmarks, with [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) as the central entry point for understanding the Hallmark design system.**

The **Nutlope/hallmark** repository is a neatly organized skill package for AI-assisted web design. Understanding how to navigate its root directory efficiently will save you time whether you're inspecting the skill definition, running the live demo, or studying the example pages. This guide maps every top-level folder to its purpose and shows you practical navigation techniques using command line tools, Node.js scripts, GitHub's web interface, and modern IDEs.

## Core Directory Structure

The repository root contains three functional areas plus supporting files. Here's how they're organized:

| Directory | Purpose | Key Files |
|-----------|---------|-----------|
| `skills/` | Skill definition and reference materials | [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) |
| `site/` | Static demo site assets | [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html), [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) |
| `docs/` | Documentation and guides | [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) |
| `site/examples/` | Ready-made example pages | [`site/examples/wayfare/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/examples/wayfare/index.html) |

### The `skills/` Directory: Skill Definition

This folder contains the **Hallmark skill manifest** that drives AI behavior. Start here to understand how the system works.

- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** — The main entry point containing the verb table, design flow, and safety rails
- **`skills/hallmark/references/`** — Linked markdown files covering structure, genres, themes, and components

Jump to specific references using the links inside [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md), such as [`references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/references/structure.md) or [`references/genres/modern-minimal.md`](https://github.com/Nutlope/hallmark/blob/main/references/genres/modern-minimal.md).

### The `site/` Directory: Live Demo Assets

Static files powering the public demo at `https://www.usehallmark.com`.

- **[`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)** — Root HTML page served by the demo
- **[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)** — Client-side JavaScript including the `T` key shortcut for cycling themes
- **`site/css/`** — Stylesheets for the demo interface

### The `site/examples/` Directory: Concrete Examples

Each subfolder represents a complete themed page with its own [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html) and [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css). Browse here to see Hallmark's output in action.

### The `docs/` Directory: Documentation

Narrative guides rather than reference material. Start with [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) for curated walkthroughs of typical use cases.

### Root-Level Files

- **[`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md)** — Project overview, live demo link, and install instructions
- **[`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)** — Minimal NPM manifest for publishing (contains `"type": "module"` and a `serve` script)

## Command Line Navigation

Use standard Unix tools for quick exploration of the repository structure.

List the top-level contents:

```bash
ls -la

```

See a two-level hierarchy at a glance:

```bash
tree -L 2

```

Find all markdown reference files:

```bash
find skills/ -name "*.md" | head -20

```

## Programmatic File Access

When building tools or scripts that consume Hallmark's skill files, reference paths from the repository root.

Load and inspect the skill manifest in Node.js:

```javascript
import { readFile } from 'fs/promises';

const skill = await readFile('skills/hallmark/SKILL.md', 'utf8');
console.log(skill.slice(0, 200)); // preview first 200 characters

```

Parse a specific genre reference:

```javascript
const genre = await readFile(
  'skills/hallmark/references/genres/modern-minimal.md',
  'utf8'
);

```

## Web-Based Navigation

Access any file directly through GitHub's raw content domain:

```

https://raw.githubusercontent.com/Nutlope/hallmark/main/<path>

```

Fetch the README programmatically:

```bash
curl https://raw.githubusercontent.com/Nutlope/hallmark/main/README.md

```

Load a specific example's source:

```bash
curl https://raw.githubusercontent.com/Nutlope/hallmark/main/site/examples/wayfare/index.html

```

## IDE Navigation Tips

Modern editors provide powerful tools for navigating this repository:

- **VS Code Outline view** — Open [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and use the outline panel to jump between sections (verb table, safety rails, references)
- **Go to Definition** — `Ctrl+Click` (or `Cmd+Click`) on reference links like [`references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/references/structure.md) to follow them
- **File nesting** — The `site/examples/` directory groups each example's files ([`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html), [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), `preview.png`) together visually

## Typical Navigation Workflows

| Goal | Steps |
|------|-------|
| **Inspect the skill definition** | Open [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) → Follow internal links to `references/` files |
| **Run the live demo locally** | Run `npm run serve` → Open `http://localhost:4173` |
| **Explore a concrete example** | Browse `site/examples/` → Choose a folder → Open its [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html) |
| **Read developer documentation** | Open [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) for narrative walkthroughs |

## Key Files Reference

Master these paths to navigate the Nutlope/hallmark repository efficiently:

- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** — Central skill entry point
- **[`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md)** — High-level project overview
- **[`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)** — Demo site root
- **[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)** — Client-side interactivity (theme cycling via `T` key)
- **[`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md)** — Curated use-case examples
- **`site/examples/<name>/index.html`** — Individual themed page examples

## Summary

- The **three core directories** are `skills/` (definition), `site/` (demo), and `docs/` (guides)
- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** serves as the canonical entry point for understanding the system
- Use **`tree -L 2`** for quick visual navigation, **Node.js `fs/promises`** for programmatic access, and **GitHub raw URLs** for direct web fetching
- The **`site/examples/`** folder contains complete, runnable examples of every theme and genre
- VS Code's **outline view** renders [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) sections as a navigable hierarchy

## Frequently Asked Questions

### How do I find the main skill definition in the hallmark repository?

The skill definition lives at **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)**. This file contains the complete verb table, design flow steps, and links to all reference materials in the `skills/hallmark/references/` subdirectory.

### What command starts the local demo server for hallmark?

Run **`npm run serve`** from the repository root. This executes the script defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), which serves the `site/` directory on `http://localhost:4173`. The command uses Vite under the hood for fast hot-reloading.

### Where are the example pages located in the hallmark repository?

Example pages sit in **`site/examples/<name>/`**. Each example is self-contained with its own [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html), [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), and optional `preview.png`. Explore `site/examples/wayfare/` or `site/examples/custom-04/` to see different genre implementations.

### How can I load hallmark skill files programmatically in Node.js?

Use **`fs/promises`** with relative paths from the repository root. Since [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) specifies `"type": "module"`, you can use ES modules: `await readFile('skills/hallmark/SKILL.md', 'utf8')`. All reference files follow predictable paths like `'skills/hallmark/references/genres/modern-minimal.md'`.