# How to Document Skills for Nutlope/hallmark: The Complete Developer Guide

> Learn how to document skills for Nutlope/hallmark. Master skill definition with markdown manifests, indexed rule-sets, and executable AI workflows in this complete developer guide.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Documenting skills for Nutlope/hallmark requires creating a self-contained markdown-based skill definition under the `skills/` directory, consisting of a [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) manifest, a `references/` corpus with indexed rule-sets, and verb-specific implementation files that define executable workflows for AI coding agents.**

The Nutlope/hallmark repository implements a modular skill system that plugs into Claude Code, Cursor, and Codex. Properly documenting these skills ensures AI agents can discover, interpret, and execute design workflows consistently across different harnesses. This guide covers the exact file structure, metadata schemas, and maintenance procedures used to document the Hallmark design skill.

## Understanding the Skill Architecture

### The Skill Manifest

Every skill begins with [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md), located at [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). This file serves as the entry point and declares the skill's metadata using a front-matter schema containing `name`, `description`, and `version` fields. The body of the manifest provides a human-readable overview of the four executable verbs (`audit`, `redesign`, `study`, and the default `build`) and describes the design workflow. When a harness loads the skill, it reads this file to discover the entry point and the location of the reference corpus.

### The Reference Corpus

The `skills/hallmark/references/` directory contains the complete rule-set that governs the skill's behavior. This corpus is loaded on demand by the skill runtime and includes:

- **Macrostructures** — 21 named page shapes (e.g., *Marquee Hero*, *Stat-Led*) defined in [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md), which enforces the diversification rule preventing consecutive runs from using the same macrostructure.
- **Themes** — 20 catalog themes (e.g., *Hum*, *Cobalt*) with colour-band, display-style, and accent-hue metadata stored in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css).
- **Anti-patterns** — A list of design tells that the skill must refuse, such as gradient heroes and centred layouts, documented in [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md).
- **Genres** — Four genre files ([`editorial.md`](https://github.com/Nutlope/hallmark/blob/main/editorial.md), [`modern-minimal.md`](https://github.com/Nutlope/hallmark/blob/main/modern-minimal.md), [`atmospheric.md`](https://github.com/Nutlope/hallmark/blob/main/atmospheric.md), [`playful.md`](https://github.com/Nutlope/hallmark/blob/main/playful.md)) that scope tone and theme rotation.

### Verb Implementations

Each executable command has its own markdown file under `skills/hallmark/references/verbs/`. The skill runtime parses the user brief, selects the appropriate verb file ([`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md), [`redesign.md`](https://github.com/Nutlope/hallmark/blob/main/redesign.md), or [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md)), and follows the step-by-step flow described within. These files contain the explicit logic for pre-flight scans, token preservation, and output generation.

## Core Documentation Components

### Macrostructures and Theme Indexes

The macrostructure index at [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) maintains the canonical list of 21 layout patterns and enforces the diversification rule. When documenting new macrostructures, you must update this index to include the new entry while preserving alphabetical order.

Theme documentation lives in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), which stores the required `--dot`, `--dot-edge`, and `--num` custom properties. These CSS variables enable the theme picker UI to render the palette correctly and allow the skill to select themes based on brief signals and diversification rules.

### Anti-Patterns and Quality Gates

The [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) file catalogs design tells that the skill must refuse. These rules feed into the slop-test gate, which runs 58 gated checks after code generation. The test logic itself resides in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md), ensuring outputs contain no invented metrics, use locked tokens, and implement mobile-ready breakpoints.

### Genre and Voice Definitions

Genre files located in `skills/hallmark/references/genres/` define the tonal boundaries for each design mode. Each file scopes the allowable theme rotations and voice characteristics, ensuring the skill maintains consistency when executing verbs under specific genre constraints.

## Step-by-Step Guide to Documenting Skills

When adding new macrostructures, themes, or verbs to Nutlope/hallmark, follow this documentation workflow:

1. **Create a markdown file** in the appropriate subfolder (`references/macrostructures/` or `references/themes/`). Use existing files as templates to maintain the same heading hierarchy and comment stamps.

2. **Update the index** ([`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) or [`themes.md`](https://github.com/Nutlope/hallmark/blob/main/themes.md)) to include the new entry, preserving alphabetical or numeric order as established in the existing corpus.

3. **Add CSS tokens** to [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) with the required `--dot`, `--dot-edge`, and `--num` custom properties so the theme picker UI can render the new palette.

4. **Run the slop-test** locally via the site's `serve` script to ensure new artifacts pass all 58 gates. Failures are reported and must be fixed before the skill returns final output.

5. **Commit changes** with a descriptive message, such as "Add 'Chronicle' macrostructure and update index".

## Working with the Hallmark CLI

The documented skill supports several CLI workflows through the `hallmark` command. The package descriptor in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) declares the skill as an npm package and lists supported harnesses (`claude-code`, `cursor`, `codex`).

Install the skill using:

```bash
npx skills add nutlope/hallmark

```

Execute the default build verb:

```bash
hallmark build "Design a landing page for a coffee subscription service"

```

Extract design DNA from existing sites:

```bash
hallmark study https://example.com/awesome-landing

```

Audit existing pages without modification:

```bash
hallmark audit ./src/pages/about.html

```

Redesign pages while preserving brand assets:

```bash
hallmark redesign ./src/pages/home.html --mood modern-minimal

```

Before any generation, Hallmark performs a pre-flight scan that examines the host project's [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, and existing [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css). The findings are emitted as a stamped comment and cached in [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) to preserve existing design tokens and framework choices.

## Summary

- **Skill metadata** lives in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which declares the skill name, version, and available verbs for harness discovery.
- **Reference documentation** resides in `skills/hallmark/references/`, containing indexed macrostructures, themes, anti-patterns, and genre definitions that govern output quality.
- **Verb workflows** are documented in `skills/hallmark/references/verbs/` as markdown files that the runtime parses to execute `audit`, `redesign`, and `study` commands.
- **Quality assurance** depends on [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) and [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md), which implement 58 gated checks to prevent design anti-patterns in generated code.
- **Theme system** requires synchronized updates to [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and the theme index to maintain the diversification rule and proper UI rendering.

## Frequently Asked Questions

### How do I add a new macrostructure to the Hallmark skill?

Create a new markdown file in `skills/hallmark/references/macrostructures/` using existing files as templates, then update [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) to include the new entry while preserving alphabetical order. Ensure the new macrostructure adheres to the diversification rule that prevents consecutive runs from using the same layout shape.

### What is the slop-test and how does it work?

The slop-test is a quality gate implemented in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) that runs 58 checks after code generation. It verifies that outputs contain no invented metrics, use locked design tokens, and implement mobile-ready breakpoints. The test references [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) to score output quality and automatically fixes failures before returning the final result.

### How does the skill handle theme diversification?

The skill selects themes based on brief signals and a diversification rule stored in the reference corpus. Theme metadata including colour-band, display-style, and accent-hue lives in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) with specific `--dot`, `--dot-edge`, and `--num` custom properties. The system prevents consecutive runs from using the same theme by checking the diversification index.

### Where are the executable verb workflows defined?

Verb implementations are documented as markdown files in `skills/hallmark/references/verbs/`, specifically [`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md), [`redesign.md`](https://github.com/Nutlope/hallmark/blob/main/redesign.md), and [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md). The skill runtime parses these files to discover the step-by-step flow for each command, including pre-flight scanning, token preservation, and the slop-test validation sequence.