Nutlope/hallmark Project Structure: Key Components of the Root Folder Explained

The Nutlope/hallmark repository root contains 10 essential components—configuration files, documentation, skill definitions, and a static demo site—that enable installation, execution, and deployment of this AI-powered design skill.

The Nutlope/hallmark project is an open-source design skill for AI coding assistants. Understanding its root folder structure is essential for contributors, integrators, and developers who want to extend or deploy the skill. This guide breaks down each component with direct references to source files.

Core Configuration Files

package.json: npm Metadata and Scripts

The package.json file defines the package name, version, entry point, and supported harnesses. It also includes a lightweight development server for local demo testing.

// From package.json
{
  "name": "hallmark",
  "version": "1.0.0",
  "scripts": {
    "serve": "npx serve site -p 4173"
  }
}

Run the local server with:

npm run serve

# Opens at http://localhost:4173

vercel.json: Deployment Configuration

The vercel.json file configures Vercel deployments for the live demo at usehallmark.com. It handles routing and build settings for the static site.

Documentation and Legal Files

README.md: Project Overview and Installation

README.md provides the high-level introduction, explains the four hallmark verbs (build, audit, redesign, study), displays example screenshots, and gives the install command:

npx skills add nutlope/hallmark

LICENSE: MIT License

The LICENSE file contains the MIT license text governing reuse and distribution.

ROADMAP.md: Future Development Plans

ROADMAP.md outlines upcoming features and the long-term vision for the skill's capabilities.

The Skill Implementation: skills/hallmark/

The skills/hallmark/ folder is the heart of the project. It contains everything AI assistants consume when the skill is invoked.

SKILL.md: Core Rule Set

skills/hallmark/SKILL.md defines the behavioral rules that drive Claude Code, Cursor, and Codex when processing design tasks.

references/: Design Reference Library

The skills/hallmark/references/ subdirectory holds detailed documentation on:

• Themes — predefined visual systems
• Typography — font pairing and scale guidelines
• Macros — reusable design patterns

These files are parsed by AI harnesses to ground their output in consistent design principles.

Demo and Testing: site/

The site/ folder powers the production demo. It contains:

Subfolder	Contents
index.html	Landing page with interactive examples
Global CSS/JS	Styling and behavior for the live preview
site/_tests/	Example pages demonstrating skill outputs

The site is deployed via Vercel and reachable at usehallmark.com.

Supplementary Documentation: docs/

The docs/ folder contains extended guides:

• docs/recipes.md — Practical walkthroughs for common use cases
• docs/study-examples.md — Sample outputs from the study verb for design DNA extraction
• Additional slide decks and reference materials

Version Control: .gitignore

The .gitignore file excludes node_modules/, build artifacts, and environment files from commits.

Summary

• Configuration: package.json and vercel.json handle metadata and deployment
• Documentation: README.md, ROADMAP.md, and docs/ provide usage guidance
• Skill core: skills/hallmark/SKILL.md and references/ define AI behavior
• Demo site: site/ serves the live preview with test examples
• Legal: LICENSE permits open reuse under MIT terms

Frequently Asked Questions

What is the purpose of the skills/hallmark/ folder?

The skills/hallmark/ folder contains the rule set and reference materials that AI coding assistants consume. The SKILL.md file defines behavior, while references/ provides design system documentation for themes, typography, and macros.

How do I run the hallmark demo locally?

Execute npm run serve from the root directory. This starts a server on port 4173 using the script defined in package.json, serving the static files from the site/ folder.

What are the four hallmark verbs?

According to README.md, the four verbs are: build (create from brief), audit (review existing code), redesign (refresh while preserving structure), and study (extract design DNA from screenshots or URLs).

Where can I find examples of hallmark outputs?

Example pages live in site/_tests/, and detailed study outputs are documented in docs/study-examples.md. These demonstrate real-world results from each verb.

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