# How to Contribute to Nutlope/hallmark: Contribution Guidelines and Workflow

> Ready to contribute to Nutlope/hallmark? Learn how to fork the repo, install the skill, and submit pull requests following contribution guidelines and passing slop-test gates.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: getting-started
- Published: 2026-07-14

---

**You can contribute to Nutlope/hallmark by forking the repository, installing the skill locally via `npx skills add nutlope/hallmark`, and submitting pull requests that follow the project's self-contained HTML/CSS architecture and pass the 57 slop-test gates.**

The Nutlope/hallmark repository hosts a design skill for Claude Code, Cursor, and Codex that generates sites refusing to look AI-generated. If you want to contribute to Nutlope/hallmark, you will work with a collection of **verbs**, **reference files**, and self-contained HTML pages that define macro-structures and design themes. While the repository does not ship a dedicated [`CONTRIBUTING.md`](https://github.com/Nutlope/hallmark/blob/main/CONTRIBUTING.md) file, the contribution guidelines can be established from the codebase structure and conventional open-source practices.

## Setting Up Your Development Environment

Before you can contribute to Nutlope/hallmark, you must install the skill locally to preview changes. According to the source code in the README, use the following command to pull the latest skill files into your local skill store [https://github.com/Nutlope/hallmark/blob/main/README.md#L95-L98](https://github.com/Nutlope/hallmark/blob/main/README.md#L95-L98):

```bash
npx skills add nutlope/hallmark

```

This command enables you to test the skill's behavior and verify that your changes render correctly before submission.

## Contribution Workflow

Since the repository lacks explicit contribution guidelines, follow this standard workflow derived from the project structure:

### Fork and Clone the Repository

Create your own copy of the repository to work in isolation:

```bash
git clone https://github.com/your-username/hallmark.git
cd hallmark

```

### Create a Feature Branch

Isolate your work by creating a descriptive branch:

```bash
git checkout -b feature/your-feature-name

```

### Make Changes to Core Files

When you contribute to Nutlope/hallmark, you will primarily edit files within three areas:

- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)**: Contains the core rule-set defining verbs, commands, and skill metadata [https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)
- **`skills/hallmark/references/`**: Houses detailed design references including macrostructures, themes, and copy guidelines [https://github.com/Nutlope/hallmark/tree/main/skills/hallmark/references](https://github.com/Nutlope/hallmark/tree/main/skills/hallmark/references)
- **`site/`**: Contains the self-contained HTML/CSS pages and the live demo entry point [https://github.com/Nutlope/hallmark/blob/main/site/index.html](https://github.com/Nutlope/hallmark/blob/main/site/index.html)

### Test Your Changes Locally

The repository includes **57 slop-test gates** to prevent AI-generated anti-patterns. Validate your work by running the test suite or opening the test pages in a browser:

```bash

# Open the test directory to verify your changes

open site/_tests/index.html

```

Test files live under `site/_tests/` and include a dedicated README explaining the harness [https://github.com/Nutlope/hallmark/blob/main/site/_tests/README.md](https://github.com/Nutlope/hallmark/blob/main/site/_tests/README.md).

### Submit a Pull Request

Push your branch and open a pull request against the main repository:

```bash
git push origin feature/your-feature-name

```

Provide a clear description of your changes, referencing any specific files modified in `skills/hallmark/` or `site/`.

## Coding Standards and Design Conventions

When you contribute to Nutlope/hallmark, adhere to these specific conventions found in the source code:

**Self-Contained Architecture**: Each page must be a single HTML file with its own CSS. Do not create external dependencies or build steps that fragment the design.

**Macro-Structure Comments**: Include design fingerprint comments in CSS headers to indicate the structure type. For example:

```css
/* macro-structure: long-document */

```

This pattern appears in reference files like [`skills/hallmark/references/macrostructures/02-long-document.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/02-long-document.md) [https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/02-long-document.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/02-long-document.md).

**Verb Naming Pattern**: Follow the existing command structure `hallmark <verb> <target>`. The four primary verbs are defined in the README under the verbs section [https://github.com/Nutlope/hallmark/blob/main/README.md#L17-L25](https://github.com/Nutlope/hallmark/blob/main/README.md#L17-L25).

**Token Management**: Store all design tokens in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and component styles in [`site/css/components.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/components.css) to maintain consistency across themes.

## Practical Example: Adding a New Theme

Here is a complete workflow for contributing a new design theme:

```bash

# Fork and clone

git clone https://github.com/your-username/hallmark.git
cd hallmark

# Create branch

git checkout -b theme-emerald

# Add color tokens to the CSS file

cat >> site/css/tokens.css <<'EOF'
/* Emerald theme */
:root {
  --primary: #2a9d8f;
  --secondary: #e9c46a;
}
EOF

# Create example page directory

mkdir -p site/examples/custom-06

# Copy template and modify

cp site/examples/custom-05/index.html site/examples/custom-06/

# Edit site/examples/custom-06/index.html to reference new tokens

# Add corresponding test file

touch site/_tests/custom/06-emerald-test.html

# Verify in browser

open site/examples/custom-06/index.html

# Commit and push

git add .
git commit -m "Add Emerald theme with tokens and example page"
git push origin theme-emerald

```

## Summary

- **Nutlope/hallmark** accepts contributions through the standard fork-and-pull-request workflow despite lacking a [`CONTRIBUTING.md`](https://github.com/Nutlope/hallmark/blob/main/CONTRIBUTING.md) file.
- Install the skill locally using `npx skills add nutlope/hallmark` to test changes before submission.
- Modify core files in `skills/hallmark/` for skill logic and `site/` for design implementations.
- Follow **self-contained HTML/CSS** architecture and include **macro-structure** comments in your CSS.
- Ensure all changes pass the **57 slop-test gates** located in `site/_tests/` before opening a pull request.

## Frequently Asked Questions

### Is there a CONTRIBUTING.md file in Nutlope/hallmark?

No, the repository does not currently include a dedicated [`CONTRIBUTING.md`](https://github.com/Nutlope/hallmark/blob/main/CONTRIBUTING.md) file. You can infer contribution guidelines from the project structure, the README installation instructions, and the conventional open-source workflow of forking, branching, and submitting pull requests.

### What coding standards should I follow when contributing?

You must adhere to a **self-contained architecture** where each page is a single HTML file with embedded CSS. Include **macro-structure comments** in your CSS headers to identify design patterns, store design tokens in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), and follow the verb naming convention `hallmark <verb> <target>` as defined in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md).

### How do I test my changes before submitting a pull request?

Run the **slop-test gates** by opening the test files in `site/_tests/` in your browser or executing the test suite locally. The repository contains 57 tests that verify your changes do not introduce AI-generated anti-patterns. You should also preview your work by opening [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) after installing the skill with `npx skills add nutlope/hallmark`.

### Can I add new design themes or verbs to the skill?

Yes, you can extend the skill by adding new reference files in `skills/hallmark/references/` and creating corresponding example pages in `site/examples/`. When adding new verbs, update [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) to document the command syntax and ensure the implementation follows the existing pattern of self-contained HTML/CSS pages.