# How Skills Are Implemented in Nutlope/hallmark: A Declarative Markdown Architecture > Discover how skills are implemented in Nutlope/hallmark using declarative Markdown modules managed by a JavaScript runtime. Learn about YAML manifests, reference docs, and execution. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: architecture - Published: 2026-07-29 --- **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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) to route commands without hard-coded logic. When the assistant receives a request starting with `hallmark `, 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`](https://github.com/Nutlope/hallmark/blob/main/audit.md) defines the self-critique rubric applied to generated code, while [`redesign.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/carnival.md), [`lumen.md`](https://github.com/Nutlope/hallmark/blob/main/lumen.md), and [`cobalt.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) and [`responsive.md`](https://github.com/Nutlope/hallmark/blob/main/responsive.md) enforce quality standards. The [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) file defines the six-axis pre-emit self-critique (scoring on performance, harmony, elegance, structure, resilience, and voice), while [`responsive.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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 `, 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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/responsive.md) for mobile breakpoints. 7. **Self-Critique** – Before returning output, the skill runs the pre-emit self-critique defined in [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/sketch.md): ```markdown --- 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 `` and `` 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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)'s "how-to-use" table. ### Invoking the Default Design Flow The following command triggers the complete pipeline: ```bash 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`](https://github.com/Nutlope/hallmark/blob/main/carnival.md), and injects tokens like `var(--color-accent)`: ```html

Fresh Coffee, Delivered

Your mornings, upgraded.

Join Now
``` ### Running the Audit Verb To validate existing markup against Hallmark’s standards: ```bash hallmark audit ./src/pages/landing.html ``` The system returns a structured report based on [`references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md): ```markdown ## 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to enable diversification. - **Quality assurance** relies on reference documents like [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) (six-axis self-critique) and [`responsive.md`](https://github.com/Nutlope/hallmark/blob/main/responsive.md) (breakpoint validation). - The **runtime engine** in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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 `.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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md). The runtime automatically discovers and executes the new verb without modifications to [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js). ### Where does Hallmark store theme history between runs? Theme selection history persists in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/responsive.md) mandates validation against four specific viewport widths (320px, 375px, 414px, and 768px). The audit verb additionally checks against [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) to identify inline colors and missing component states.