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

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 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:

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:

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

Create a Feature Branch

Isolate your work by creating a descriptive branch:

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: Contains the core rule-set defining verbs, commands, and skill metadata 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
• site/: Contains the self-contained HTML/CSS pages and the live demo entry point 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:

# 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.

Submit a Pull Request

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

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:

/* 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.

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.

Token Management: Store all design tokens in site/css/tokens.css and component styles in 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:

# 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 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 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, and follow the verb naming convention hallmark <verb> <target> as defined in 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 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 to document the command syntax and ensure the implementation follows the existing pattern of self-contained HTML/CSS pages.

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