What Is the Purpose of Each Root‑Level File in the Nutlope/hallmark Repository?

Bold TLDR: Every file in hallmarks root directory serves a distinct packaging, configuration, or documentation role that enables the Hallmark design skill to be installed into AI coding assistants and deployed to Vercel.

The Hallmark repository is a compact, self-contained design skill for AI coding assistants such as Claude Code, Cursor, and Codex. Understanding what each root-level file does helps developers install, configure, and contribute to the project correctly. Below is a definitive breakdown of every top-level file and directory in Nutlope/hallmark, grounded in the actual source code.

---

README.md: Primary Entry Point and Documentation

The README.md file provides the public-facing overview of Hallmark. It explains what the skill does, which verbs it supports, showcases example galleries, and delivers installation instructions along with licensing information.

Anyone browsing the repository on GitHub encounters this file first. It functions as both marketing material and technical quick-start guide.

---

package.json: NPM Metadata and skill Loader Configuration

The package.json file supplies standard npm metadata—name, version, description, and keywords—but serves a more critical purpose for Hallmark.

It defines the skill entry point as skills/hallmark/SKILL.md, which is required by the skill-loader infrastructure used by AI assistants. Without this mapping, assistants would not know which file to load.

The file also includes a minimal development script:

{
  "scripts": {
    "serve": "vite preview --outDir site"
  }
}

Running npm run serve launches a local preview of the static site at http://localhost:4173.

---

vercel.json: Deployment Configuration for Vercel

The vercel.json file configures Vercel deployments for the static site/ folder. It explicitly disables build steps and designates the output directory:

{
  "framework": null,
  "outputDirectory": "site"
}

This configuration enables the live demo at https://www.usehallmark.com without requiring a build pipeline.

---

LICENSE: MIT License Declaration

The LICENSE file declares the project's MIT license, granting permissive reuse while requiring attribution. This standard open-source license allows Hallmark to be incorporated into commercial and non-commercial projects alike.

---

ROADMAP.md: Feature Planning and Contributor Guidance

The ROADMAP.md file outlines upcoming features, bug fixes, and longer-term goals for Hallmark. Specific items include new themes, additional verbs, and tighter integration with slop tests.

Contributors consult this file to understand project direction and identify areas where contributions are most needed.

---

.gitignore: Repository Hygiene

The .gitignore file lists files and directories that must never be committed to version control. Typical exclusions include IDE caches, dependency folders, and built assets.

Maintaining a clean .gitignore reduces repository noise and prevents sensitive or ephemeral files from entering the commit history.

---

opencode.json and .cache_meta.json: Tooling Metadata

These two files are auto-generated metadata used by Open Code tooling for fast indexing and caching. They are not part of Hallmark's runtime or skill functionality.

Developers should not manually edit these files; they exist solely to accelerate development tooling operations.

---

Directories: site/, skills/, and docs/

site/ — Static Demo Playground

The site/ directory holds the static HTML, CSS, and JavaScript that powers the live demo. Files inside include:

• index.html — Main demo page
• css/ — Stylesheet assets
• js/ — Client-side scripts

These files represent the concrete output of applying Hallmark's design skill and illustrate what generated UIs look like.

skills/ — Core skill Definition

The skills/ directory contains the actual skill implementation:

• skills/hallmark/SKILL.md — The rule-set that AI assistants load and execute
• skills/hallmark/references/ — Markdown files defining macro-structures, themes, and typographic tokens

When you install Hallmark via npx skills add nutlope/hallmark, the tooling copies these files into your assistant's skill directory.

docs/ — Extended Documentation and Recipes

The docs/ directory provides human-readable documentation beyond the README:

• recipes.md — Common invocation patterns
• study-examples.md — Annotated example outputs
• Screenshots and visual references

These materials help developers learn how to effectively invoke Hallmark's verbs.

---

How to Use Hallmark: Practical Commands

Install Hallmark as a skill in your AI assistant:

npx skills add nutlope/hallmark

Preview the static demo locally:

npm run serve

Reference the skill entry point programmatically:

{
  "skill": {
    "entry": "node_modules/hallmark/skills/hallmark/SKILL.md",
    "references": "node_modules/hallmark/skills/hallmark/references"
  }
}

---

Summary

• README.md — Human-readable overview and quick-start guide
• package.json — NPM package definition and skill entry point mapping
• vercel.json — Zero-build Vercel deployment configuration
• LICENSE — MIT license for permissive reuse
• ROADMAP.md — Planned features and contributor direction
• .gitignore — Version control exclusions
• opencode.json & .cache_meta.json — Auto-generated tooling metadata
• site/ — Static demo files deployed to usehallmark.com
• skills/ — Core SKILL.md and reference library loaded by AI assistants
• docs/ — Extended documentation, recipes, and visual examples

These files together make Hallmark a plug-and-play design skill that transforms AI-generated UIs into handcrafted-looking designs.

---

Frequently Asked Questions

What file do AI assistants actually load when Hallmark is installed?

AI assistants load skills/hallmark/SKILL.md. The package.json file specifies this path as the skill entry point, and the skill-loader infrastructure follows this mapping.

Why does vercel.json set framework to null?

Setting "framework": null tells Vercel that no build step is required. Hallmark's demo is purely static files in the site/ directory, so Vercel deploys them directly without running a build pipeline.

Are opencode.json and .cache_meta.json safe to delete?

Yes. These files are auto-generated by Open Code tooling for caching and indexing. They will be recreated automatically and do not affect Hallmark's functionality.

How do I preview changes to the site/ directory locally?

Run npm run serve from the repository root. This launches a local server at http://localhost:4173 using Vite's preview mode with site/ as the output directory.

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