How to Integrate Hallmark with Your Project: Complete Setup Guide

You can integrate Hallmark into Claude Code, Cursor, or Codex by running npx skills add nutlope/hallmark, which installs the skill definition and enables the hallmark command for generating anti-AI-slop designs.

Integrating Hallmark with your project adds a disciplined design skill to your AI coding assistant. According to the Nutlope/hallmark source code, this skill generates fully-styled pages and components that follow a strict design system, eliminating generic AI-generated aesthetics through a deterministic pipeline and 58-gate compliance tests.

Installing the Hallmark Skill

One-Step Installation Command

Run the following command in your terminal to register Hallmark for your current environment:

npx skills add nutlope/hallmark

This command pulls the skill definition from skills/hallmark/SKILL.md and registers it for the current user, project, or environment. The installation is idempotent and only needs to be run once per machine or workspace.

Where Skill Files Are Stored

After installation, the skill files are written to assistant-specific locations:

• Claude Code: ~/.claude/skills/hallmark/
• Cursor: .cursor/rules/hallmark.mdc (contains the body of SKILL.md without front-matter)
• Codex: ~/.codex/skills/hallmark/ (personal) or .codex/skills/hallmark/ (project-scoped)

These paths ensure that the skill persists across sessions and is available whenever you invoke your AI assistant.

Using Hallmark Commands in Your Project

Once installed, you can invoke Hallmark through four primary command patterns defined in SKILL.md.

Default Design Flow

Running the base command initiates the full design pipeline:

hallmark

This executes the complete workflow from pre-flight scan through build & slop-test, generating a new UI that follows the anti-AI-slop design system.

Audit Mode

To evaluate existing code without making changes, use the audit verb:

hallmark audit ./src/pages/about.html

This command scores the target file against anti-patterns and the 58-gate slop-test, providing feedback on design compliance without modifying your source.

Redesign Mode

To rebuild the visual layer while preserving routes, copy, and information architecture:

hallmark redesign ./src/components/Button.tsx --mood modern-minimal

The --mood flag accepts values like modern-minimal, playful, editorial, or atmospheric to control the genre selection.

Study Mode

Extract design DNA from reference materials:

hallmark study https://example.com

This analyzes a screenshot or live URL and locks the extracted visual patterns for use in subsequent generations.

Understanding the Hallmark Design Pipeline

When you invoke the default hallmark command, the skill executes a deterministic seven-stage pipeline defined in skills/hallmark/SKILL.md:

1. Pre-flight scan – Reads existing package.json, Tailwind config, and design tokens to preserve your current design system.

2. Genre detection – Selects one of four genres (editorial, modern-minimal, atmospheric, playful) based on brief signals.

3. Macrostructure selection – Chooses a named macrostructure from the index (e.g., Marquee Hero, Bento Grid) while respecting diversification rules.

4. Theme route – Selects either a catalog theme or a custom theme if the brief explicitly requests a bespoke palette.

5. Enrichment decision – Determines whether hero enrichment (illustration, video, Lottie) is required for the design.

6. Preview – Emits a concise markdown preview of the planned output before generating code, allowing you to validate the approach.

7. Build & slop-test – Produces HTML/CSS with token-based color and font references, then runs the 58-gate slop-test to ensure compliance with anti-AI-slop rules.

Key Configuration Files and References

The following files control how Hallmark integrates with your project and generates output:

• README.md – High-level overview and installation instructions.
• skills/hallmark/SKILL.md – Core skill definition containing the verb specifications and discipline rules.
• docs/recipes.md – Ready-to-paste prompts for landing pages, component builds, and audits.
• references/macrostructures.md – Index of the 21 macrostructures available to the design flow.
• references/genres/editorial.md (and peers) – Genre-specific design tokens and constraints.
• site/css/tokens.css – Token definitions for colors, fonts, and spacing used by generated code.

Summary

• Install Hallmark across Claude Code, Cursor, or Codex using npx skills add nutlope/hallmark.
• Skill files are stored in assistant-specific directories like ~/.claude/skills/hallmark/ or .cursor/rules/hallmark.mdc.
• Use hallmark to build new UIs, hallmark audit to score existing code, hallmark redesign to refresh visuals, and hallmark study to extract design DNA.
• The design pipeline includes pre-flight scanning, genre detection, macrostructure selection, and a 58-gate slop-test to ensure quality.
• Reference docs/recipes.md for common usage patterns and skills/hallmark/SKILL.md for complete command specifications.

Frequently Asked Questions

What AI assistants support Hallmark integration?

Hallmark supports Claude Code, Cursor, and OpenAI Codex. Each assistant stores the skill files in a specific location—Claude Code uses ~/.claude/skills/, Cursor uses .cursor/rules/, and Codex uses either ~/.codex/skills/ for personal installs or .codex/skills/ for project-scoped installations.

How does Hallmark prevent AI slop in generated code?

The skill implements a 58-gate slop-test during the final build stage that validates compliance with strict anti-pattern rules. It also follows a deterministic pipeline including genre detection and macrostructure selection from curated indexes rather than generating arbitrary layouts.

Can I customize the visual theme when using Hallmark?

Yes. When using hallmark redesign, you can specify a mood using the --mood flag with values like playful, editorial, modern-minimal, or atmospheric. The skill also preserves existing design tokens from your package.json and Tailwind configuration during the pre-flight scan.

Where can I find example prompts for common use cases?

The docs/recipes.md file contains ready-to-copy prompts for typical scenarios including landing page generation, component builds, and code audits. This file demonstrates how to structure briefs that trigger specific macrostructures and genre selections.

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