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

Use the skills/, site/, and docs/ directories as your primary landmarks, with 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
site/	Static demo site assets	site/index.html, site/js/main.js
docs/	Documentation and guides	docs/recipes.md
site/examples/	Ready-made example pages	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 — 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, such as references/structure.md or 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 — Root HTML page served by the demo
• 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 and 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 for curated walkthroughs of typical use cases.

Root-Level Files

• README.md — Project overview, live demo link, and install instructions
• 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:

ls -la

See a two-level hierarchy at a glance:

tree -L 2

Find all markdown reference files:

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:

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:

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:

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

Load a specific example's source:

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 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 to follow them
• File nesting — The site/examples/ directory groups each example's files (index.html, tokens.css, preview.png) together visually

Typical Navigation Workflows

Goal	Steps
Inspect the skill definition	Open 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
Read developer documentation	Open docs/recipes.md for narrative walkthroughs

Key Files Reference

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

• skills/hallmark/SKILL.md — Central skill entry point
• README.md — High-level project overview
• site/index.html — Demo site root
• site/js/main.js — Client-side interactivity (theme cycling via T key)
• 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 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 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. 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, 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, 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 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'.

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