How the Root package.json Defines Nutlope/hallmark: Complete Manifest Breakdown

The root package.json in Nutlope/hallmark serves as the single source of truth that declares the hallmark skill, combining standard npm metadata with Instagit-specific configuration to make it discoverable and executable by AI platforms. This manifest follows conventional npm structure while extending it with a custom skill block that controls how Instagit-compatible harnesses discover, load, and invoke the skill.

The Nutlope/hallmark repository implements a skill designed to make AI-generated UIs look polished and professional rather than obviously generated. Its package.json bridges the gap between npm's package ecosystem and Instagit's skill execution framework, enabling seamless integration with Claude Code, Cursor, and Codex.

Standard npm Fields in hallmark's package.json

The manifest begins with familiar npm fields that establish identity and compatibility across JavaScript ecosystems.

name, version, and description

These core identifiers appear at lines 2-4 of [package.json](https://github.com/Nutlope/hallmark/blob/main/package.json#L2):

{
  "name": "hallmark",
  "version": "1.0.0",
  "description": "Makes the UIs they generate look made, not generated"
}

Instagit platforms use "hallmark" as the public skill name for lookups and references. The semantic version enables version constraint enforcement when dependencies specify compatibility ranges.

keywords for Discoverability

Lines 5-16 populate the keywords array with platform and domain tags:

"keywords": [
  "claude",
  "cursor",
  "design",
  "ui",
  "hallmark",
  "skill",
  "instagit"
]

These tags power search and filtering in skill catalogs, connecting users with relevant capabilities based on their tooling and use case.

Module Type and File Distribution

The configuration declares ES module support and restricts published content:

"type": "module",
"files": ["skills"]

• "type": "module" (line 19): Enables import/export syntax without file extensions
• "files": ["skills"] (lines 20-22): Bundles only the skills directory, excluding development artifacts, documentation, and the site/ folder from npm packages

The Custom skill Block: Instagit Integration

The package.json extends beyond npm conventions with a skill object that defines how Instagit harnesses interact with hallmark. This custom configuration occupies lines 23-31.

Skill Entry Point

The skill.entry field specifies where to find the skill's interface definition:

"skill": {
  "entry": "skills/hallmark/SKILL.md"
}

This markdown file at [skills/hallmark/SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) contains the human-readable description of capabilities, input schemas, and expected outputs. Instagit reads this file to parse the skill's contract.

Reference Materials

The references directory provides supplemental context:

"references": "skills/hallmark/references"

Located at skills/hallmark/references, this folder contains design guidelines, examples, and documentation that AI harnesses can ingest to improve execution quality.

Compatible Harnesses

The harnesses array declares which AI platforms can execute this skill:

"harnesses": [
  "claude-code",
  "cursor",
  "codex"
]

This whitelist (lines 27-30) tells Instagit which back-ends have been tested and validated against hallmark's interface. Platforms not listed may still attempt execution, but without official compatibility guarantees.

Development and Runtime Scripts

The scripts section includes tooling for local development:

"scripts": {
  "serve": "serve site"
}

Running npm run serve (line 33) launches an HTTP server at http://localhost:4173 to preview the static site generated for documentation and demonstration.

Practical Usage Examples

Installing from Git

For local development or testing the skill definition:

npm install https://github.com/Nutlope/hallmark.git

Loading Skill Entry Programmatically

In a Node.js ES module environment:

import { readFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

const skillPath = new URL('skills/hallmark/SKILL.md', import.meta.url);
const skillMarkdown = await readFile(fileURLToPath(skillPath), 'utf8');
console.log(skillMarkdown);

Executing via Instagit Harness

Pseudo-code for platform integration:

await harness.executeSkill({
  name: 'hallmark',
  version: '^1.0.0',
  input: {
    // UI design requirements, style preferences, constraints
  }
});

Key File Relationships

Understanding how package.json connects to other repository files:

File	Relationship to package.json
package.json	Central manifest; defines all metadata and skill configuration
skills/hallmark/SKILL.md	Target of skill.entry; describes interface contract
skills/hallmark/references/	Target of skill.references; supplemental execution context
site/	Served by npm run serve; documentation and demonstration assets

The Instagit Discovery Flow

When an Instagit-compatible platform encounters the Nutlope/hallmark repository, it performs this resolution sequence:

1. Read package.json and validate presence of skill object
2. Verify that the current harness appears in skill.harnesses
3. Load the markdown content from skill.entry to parse the interface
4. Ingest reference materials from skill.references if available
5. Execute skill invocations against the defined contract

This architecture separates packaging concerns (npm) from execution semantics (Instagit), allowing hallmark to exist in both ecosystems without duplication.

Summary

• The root package.json in Nutlope/hallmark combines standard npm manifest fields with a custom skill block for Instagit compatibility
• The name field ("hallmark") serves as the public skill identifier across platforms
• The skill.entry points to skills/hallmark/SKILL.md for interface specification
• The skill.harnesses array whitelists compatible AI platforms: Claude Code, Cursor, and Codex
• "type": "module" enables modern ES module syntax throughout the package
• npm run serve provides local preview of the documentation site

Frequently Asked Questions

What makes the hallmark package.json different from a standard npm package?

The hallmark package.json extends npm conventions with a top-level skill object containing entry, references, and harnesses properties. These custom fields enable Instagit platforms to discover, load, and execute the skill, while standard fields maintain compatibility with npm's package ecosystem.

Why does the files array only include the skills directory?

The "files": ["skills"] restriction at lines 20-22 ensures minimal npm bundle size by excluding development tooling, documentation sites, and build artifacts. Only the essential skill definition and reference materials ship to production environments, reducing install time and disk usage.

How do I know which AI platforms can run the hallmark skill?

The skill.harnesses array explicitly lists compatible platforms. In Nutlope/hallmark, this includes "claude-code", "cursor", and "codex" (lines 27-30). Instagit harnesses check this list before executing to ensure validated compatibility.

Can I use hallmark as a regular npm dependency in my project?

Yes. The ES module configuration ("type": "module") and standard npm fields make hallmark installable via npm install https://github.com/Nutlope/hallmark.git. However, primary usage targets Instagit-compatible AI platforms rather than direct programmatic consumption.

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