How Skills Are Implemented in Nutlope/hallmark: A Declarative Markdown Architecture

Hallmark implements skills as declarative, Markdown-based modules under the skills/ directory, where a YAML front-matter manifest pairs with reference documents to define executable verbs, design themes, and validation rules, all orchestrated by the JavaScript runtime in site/js/main.js.

The Nutlope/hallmark repository uses a novel approach to skill implementation that relies entirely on Markdown files rather than compiled code. Each skill exists as a self-contained module utilizing a manifest file and reference documents to guide the LLM assistant through complex design workflows. This architecture makes the skill system extensible, transparent, and version-controlled through standard documentation practices.

Core Architecture of Hallmark Skills

Hallmark’s skill system centers on a Markdown-only representation that requires no procedural compilation. The architecture separates metadata from implementation, storing declarative instructions in structured text files that the runtime parses dynamically.

At the root of every skill resides SKILL.md, a manifest file containing YAML front-matter that declares the skill’s name, version, and purpose. This manifest acts as the entry point for the LLM assistant, containing a "how-to-use" table that maps natural language invocations to specific verb references. Unlike traditional plugin systems that require JavaScript registration, Hallmark discovers capabilities by scanning the references/ subdirectory for Markdown files following specific naming conventions.

Skill Components and File Structure

The implementation relies on four distinct component types that collaborate during execution.

The Skill Manifest

Located at skills/hallmark/SKILL.md, the manifest defines the skill’s metadata and acts as the central registry. It contains a table mapping verb names to their corresponding reference files, enabling the runtime in site/js/main.js to route commands without hard-coded logic. When the assistant receives a request starting with hallmark <verb>, the runtime consults this manifest to locate the appropriate implementation guide.

Verb Definitions

Concrete commands like audit, redesign, and study live as individual Markdown files in skills/hallmark/references/verbs/. Each verb file specifies input parameters, processing logic, and output shapes using structured Markdown headers and bullet lists. For example, audit.md defines the self-critique rubric applied to generated code, while redesign.md outlines the transformation pipeline for existing HTML.

These verb files contain no executable JavaScript; instead, they provide declarative instructions that the LLM follows to construct responses. Adding a new verb requires only creating a new Markdown file in this directory and updating the manifest’s verb table.

Design References and Themes

The skills/hallmark/references/ directory houses reusable design knowledge organized by category. The themes/ subdirectory contains 20 named theme files—such as carnival.md, lumen.md, and cobalt.md—each defining token palettes and font pairings using CSS custom properties. Macro-structure files in references/macrostructures/ define page rhythms like "hero → features → CTA → footer" to guarantee structural variety across generations.

Constraint documents like slop-test.md and responsive.md enforce quality standards. The slop-test.md file defines the six-axis pre-emit self-critique (scoring on performance, harmony, elegance, structure, resilience, and voice), while responsive.md mandates validation against four viewport widths: 320px, 375px, 414px, and 768px.

Runtime Engine and State Management

The JavaScript file site/js/main.js serves as the execution engine, parsing the skill manifest and reference documents to orchestrate the design pipeline. It maintains session state in .hallmark/log.json, a generated file that tracks which theme was used for each page run. This log enables the "diversification rule" that rotates themes across successive builds to prevent visual stagnation.

The Skill Execution Pipeline

When a user invokes a Hallmark skill, the runtime executes a seven-stage pipeline defined in the reference documents.

1. Invocation Parsing – The runtime examines the natural language request. If the utterance matches hallmark <verb>, it resolves the verb via the reference files in skills/hallmark/references/verbs/; otherwise, it selects the default design flow.

2. Pre-Flight Checks – The system enforces safety rails defined in the manifest, including prohibitions on file deletions, mandatory token-only color usage, and adherence to 8-state component rules.

3. Theme Routing – Step 2.6 of the flow selects a theme from references/themes/*.md or constructs a custom OKLCH palette when the brief signals creative intent. The engine consults .hallmark/log.json to avoid repeating the previous selection.

4. Macro-Structure Selection – Using files in references/macrostructures/, the engine selects a page rhythm that ensures structural variety while respecting existing routes and component ownership.

5. Component Generation – The system injects design tokens (e.g., var(--color-accent)) and emits component scaffolding according to the chosen macro-structure. The skill emits only additive code unless the user explicitly requests deletions.

6. Responsive Validation – Generated markup undergoes verification against the non-negotiable rules in responsive.md for mobile breakpoints.

7. Self-Critique – Before returning output, the skill runs the pre-emit self-critique defined in slop-test.md. Any score below 3 on the six-axis rubric triggers an automatic revision pass.

Practical Implementation Examples

Extending Hallmark’s skill system requires only Markdown editing.

Adding a New Verb

To create a sketch verb that generates low-fidelity wireframes, create skills/hallmark/references/verbs/sketch.md:

---
name: sketch
description: Generate a low‑fidelity wireframe from a brief.
---

**Goal** – Produce a `.svg` wireframe that respects the chosen macro‑structure.

### Implementation notes

- Use the same token palette as the selected theme.
- Emit only `<rect>` and `<line>` elements; no text content.
- Return the SVG wrapped in a fenced code block.

No JavaScript changes are required. The runtime automatically surfaces the verb once it appears in SKILL.md's "how-to-use" table.

Invoking the Default Design Flow

The following command triggers the complete pipeline:

hallmark design "Create a landing page for a new coffee subscription service"

The runtime generates HTML following the catalog theme selected from references/themes/, such as carnival.md, and injects tokens like var(--color-accent):

<!-- Hallmark · pre‑emit critique: P5 H5 E5 S5 R5 V5 -->
<link rel="stylesheet" href="tokens.css">
<header class="hero">
  <h1 class="display">Fresh Coffee, Delivered</h1>
  <p class="lead">Your mornings, upgraded.</p>
  <a class="cta" href="/signup">Join Now</a>
</header>

Running the Audit Verb

To validate existing markup against Hallmark’s standards:

hallmark audit ./src/pages/landing.html

The system returns a structured report based on references/anti-patterns.md:

## Hallmark Audit – Landing Page

- **Repeated colour token** | Severity: 2/5 | Consolidate into `--color-primary`
- **Missing 8‑state button** | Severity: 1/5 | Add hover, focus‑visible, active, disabled, loading, error, success states
- **Inline colour value** | Severity: 3/5 | Replace `#ff7a00` with `var(--color-accent)`

Summary

• Hallmark skills reside in skills/hallmark/ as declarative Markdown modules, with SKILL.md serving as the central manifest.
• Verb definitions in references/verbs/*.md define executable commands like audit and redesign without requiring JavaScript implementation.
• The theme system uses 20 catalogued palettes stored in references/themes/*.md, with selection history tracked in .hallmark/log.json to enable diversification.
• Quality assurance relies on reference documents like slop-test.md (six-axis self-critique) and responsive.md (breakpoint validation).
• The runtime engine in site/js/main.js parses Markdown instructions to orchestrate the seven-stage design pipeline, making the system fully extensible through documentation edits alone.

Frequently Asked Questions

What makes Hallmark skills "declarative"?

Hallmark skills are declarative because they consist entirely of Markdown documentation with YAML front-matter rather than imperative code. The runtime in site/js/main.js parses these text files to extract structured data—such as verb parameters in references/verbs/*.md and theme tokens in references/themes/*.md—and instructs the LLM to follow these guidelines. This approach treats skills as configuration rather than code, enabling version control and modification without JavaScript changes.

How do I add a new verb to the Hallmark skill system?

Create a new Markdown file in skills/hallmark/references/verbs/ following the naming convention <verb>.md, include YAML front-matter with name and description fields, and document the implementation steps using standard Markdown headers. Then add the verb to the "how-to-use" table in skills/hallmark/SKILL.md. The runtime automatically discovers and executes the new verb without modifications to site/js/main.js.

Where does Hallmark store theme history between runs?

Theme selection history persists in .hallmark/log.json, a JSON file generated during each execution. This log records which theme from references/themes/ was applied to each page, enabling the diversification rule that prevents immediate theme reuse. The runtime consults this file during the theme routing stage to ensure visual variety across successive builds.

What validates the generated HTML/CSS output?

Two reference documents enforce output quality: slop-test.md defines a six-axis self-critique rubric (Performance, Harmony, Elegance, Structure, Resilience, Voice) that must score 3 or higher on each axis before emission, while responsive.md mandates validation against four specific viewport widths (320px, 375px, 414px, and 768px). The audit verb additionally checks against anti-patterns.md to identify inline colors and missing component states.

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