Nutlope/hallmark Project Structure: A Deep Dive Into the 3 Core Components

The Nutlope/hallmark repository consists of three primary components: the site/ directory for the public demo and documentation, the skills/hallmark/ directory containing the AI skill definition and verb specifications, and the runtime-generated .hallmark/ directory for persistent design-system state and caching.

The hallmark project is an AI-powered UI skill platform that enables Claude-based agents to generate, audit, and redesign web interfaces through natural language commands. Understanding its project structure is essential for contributors, integrators, and developers who want to extend the platform or debug its behavior. This article examines each component through the lens of the actual source code, referencing specific files and their responsibilities as implemented in the Nutlope/hallmark repository.

The Three Pillars of the Hallmark Architecture

The hallmark project organizes its functionality around three interconnected pillars. Each pillar serves a distinct purpose in the skill's lifecycle from demonstration to execution to state persistence.

Component	Purpose	Location
site/	Static website for demos, installation instructions, and interactive UI	site/
skills/hallmark/	Skill definition consumed by Claude-based agents	skills/hallmark/
.hallmark/	Runtime cache and log files for design-system decisions	Generated at runtime

Supporting materials in docs/ and ROADMAP.md provide human-readable documentation, but these three pillars constitute the executable architecture.

Component 1: The site/ Directory (Public Front-End)

The site/ directory hosts the public-facing demonstration of hallmark capabilities. This static website allows potential users to explore the skill without local installation.

HTML Entry Point and Demo Interface

The file site/index.html serves as the primary entry point. It contains:

• A banner linking to the GitHub repository
• A theme selector for previewing different visual treatments
• Pre-written hallmark prompts showcasing command patterns

Lines 247–334 of site/index.html expose example commands such as:

hallmark build a landing page for a small-batch honey farm

These prompts demonstrate how users interact with the skill's natural language interface.

Styling and Visual Language

The CSS architecture spans multiple files:

• site/css/base.css – foundational styles
• site/css/components.css – UI component definitions

The component stylesheet includes hallmark-specific selectors, notably [data-variant="hallmark"] (lines 1262–1324), which applies distinctive styling to hallmark-generated outputs.

Client-Side Logic and Interactivity

The file site/js/main.js handles:

• Theme persistence: Uses STORAGE_KEY = "hallmark-theme" (line 65) to save user preferences across sessions
• Installation workflow: Implements a copy-to-clipboard feature for the installation command npx skills add nutlope/hallmark (lines 840–906)

This component transforms abstract skill capabilities into tangible, interactive demonstrations.

Component 2: The skills/hallmark/ Directory (AI Skill Definition)

The skills/hallmark/ directory contains the machine-readable specifications that Claude-based agents parse to execute hallmark commands. This is the core intellectual property of the project.

SKILL.md: The Canonical Manifest

The file skills/hallmark/SKILL.md serves as the authoritative source of truth for agent behavior. It specifies:

• Three core verbs: audit, redesign, and study
• Behavior constraints for each verb
• Output format specifications
• The "slop test" for detecting AI-generated anti-patterns
• Diversification rules preventing repetitive outputs
• The design.md lockfile mechanism for preserving design decisions

Lines 2–153 of SKILL.md define the complete verb specification that agents use to route user requests.

Reference Documentation Architecture

The subdirectory skills/hallmark/references/ contains granular documentation for every aspect of the skill's internal language:

Reference File	Contents
verbs/redesign.md	Multi-page redesign workflow and state management
verbs/audit.md	Anti-pattern detection logic and ranking
verbs/study.md	URL-based DNA extraction methodology
custom-theme.md	Theme axis recording in .hallmark/log.json (lines 210–240)
component-cookbook.md	Reusable UI blocks (Bento grids, product-card grids, etc.)

These files are read-only at runtime. The hallmark agent consults them to determine which macro-structure, theme, and enrichment parameters to apply.

Component Cookbook and Reusable Patterns

The references/component-cookbook.md enumerates composable UI blocks that hallmark assembles during builds. This modular approach enables the skill to construct varied interfaces from a constrained but expressive vocabulary of patterns.

Component 3: The .hallmark/ Directory (Persistent State)

Unlike the previous components, .hallmark/ is generated at runtime and excluded from version control. It serves as the memory layer that makes hallmark intelligent across multiple invocations.

Log File: .hallmark/log.json

Every hallmark run appends a structured entry to .hallmark/log.json:

{
  "date": "YYYY-MM-DD",
  "macrostructure": "<name>",
  "theme": "<name>",
  "enrichment": "<E# name or 'none'>",

  "brief": "<one-line summary>"
}

This log enables two critical capabilities:

1. Diversification: Prevents consecutive builds from reusing identical navigation or footer archetypes
2. Consistency preservation: Allows the redesign verb to read previous selections and maintain visual coherence

Lines 298–346 of SKILL.md document how the log file drives these behaviors.

Preflight Cache: .hallmark/preflight.json

The preflight file stores expensive computation results, particularly from URL-mode study operations. When a user runs hallmark study https://example.com, the extracted design DNA gets cached here. Subsequent runs reuse this data unless the user explicitly forces a refresh (lines 177–191).

Practical Workflow Integration

Understanding how components interact clarifies the hallmark execution model.

Installation Flow

npx skills add nutlope/hallmark

This command (exposed via the copy-to-clipboard feature in site/js/main.js) registers the skill with the local Claude environment.

Build Execution

hallmark build "a landing page for a small-batch honey farm" modern-minimal

The agent parses SKILL.md to:

1. Map build to the internal hallmark default flow
2. Select an appropriate macro-structure
3. Apply the modern-minimal theme if available in the theme registry
4. Write a new entry to .hallmark/log.json
5. Return generated HTML/CSS

Audit and Study Operations

hallmark audit ./hero.tsx
hallmark study https://example.com/brand-landing

The audit verb consults references/anti-patterns.md (lines 3–7) to produce ranked improvement recommendations. The study verb extracts and caches design DNA to .hallmark/preflight.json per references/study.md (lines 3–30).

Key Files for Deep Reference

File	Role
site/index.html	Demo landing and installation instructions
site/js/main.js	Theme persistence and install-command UI
skills/hallmark/SKILL.md	Verb manifest and execution rules
skills/hallmark/references/verbs/redesign.md	Multi-page redesign specification
skills/hallmark/references/verbs/audit.md	Anti-pattern audit logic
skills/hallmark/references/verbs/study.md	URL study and DNA extraction
.hallmark/log.json	Generated design-system log
docs/README.md	Project overview and roadmap
ROADMAP.md	Future development plans

Summary

• The site/ directory provides public demonstration and installation pathways through index.html, component CSS, and main.js with theme persistence.

• The skills/hallmark/ directory encodes agent behavior through SKILL.md and granular reference documentation, defining how audit, redesign, and study verbs execute.

• The .hallmark/ directory persists state across runs via log.json (design-system history) and preflight.json (computation caching), enabling diversification and consistency.

• Cross-component integration occurs through the skill manifest: SKILL.md references files in site/ for examples and writes to .hallmark/ for state management.

Frequently Asked Questions

What makes the skills/hallmark/ directory different from typical source code?

The skills/hallmark/ directory contains declarative specifications rather than imperative code. Files like SKILL.md are parsed by Claude-based agents at runtime to determine behavior. This architecture separates what the skill does from how the AI implements it, allowing the same specification to evolve with underlying model capabilities.

Why does hallmark need a .hallmark/ log file instead of being stateless?

The .hallmark/log.json file enables diversification rules that prevent repetitive outputs and consistency preservation across redesign operations. Without this state, the redesign verb could not respect previous macro-structure or theme selections, and consecutive builds might produce visually identical navigation patterns.

How does the site/ directory relate to the actual skill execution?

The site/ directory operates independently of skill execution but serves critical ecosystem functions: it demonstrates capabilities to prospective users, provides installation instructions, and hosts interactive examples. The main.js file coordinates with the skill definition by surfacing the identical installation command (npx skills add nutlope/hallmark) that SKILL.md assumes.

Where are the hallmark verbs actually implemented?

The verb implementations reside in the Claude agent runtime, not in this repository. The skills/hallmark/ directory provides the specification that the agent consumes. Files like references/verbs/audit.md describe what constitutes an anti-pattern and how to rank findings, but the actual parsing and analysis occurs within the AI system interpreting these documents.

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