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

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 — 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 to discover available commands and loads reference files as needed for context.

# 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 — 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.

# 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 — Practical "how-to" workflows for common tasks
• talk-slides.md — Presentation materials explaining the skill's architecture
• 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	Root	Project overview, live demo URL, quick start
SKILL.md	skills/hallmark/	Skill manifest with verbs and rules
index.html	site/	Demo site root
package.json	Root	Dependencies (framer-motion, tailwind) and build scripts
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:

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 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 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 in a browser, or serve it via a local HTTP server. The site/examples/ folder contains standalone pages like 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.

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