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

> Discover how the root package.json defines Nutlope/hallmark. Learn about npm metadata and custom skill blocks for AI platform discoverability and execution.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: api-reference
- Published: 2026-08-18

---

**The root [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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)](https://github.com/Nutlope/hallmark/blob/main/package.json#L2):

```json
{
  "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:

```json
"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:

```json
"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`](https://github.com/Nutlope/hallmark/blob/main/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:

```json
"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)](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:

```json
"references": "skills/hallmark/references"

```

Located at [`skills/hallmark/references`](https://github.com/Nutlope/hallmark/tree/main/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:

```json
"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:

```json
"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:

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

```

### Loading Skill Entry Programmatically

In a Node.js ES module environment:

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

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

```

## Key File Relationships

Understanding how [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) connects to other repository files:

| File | Relationship to package.json |
|------|------------------------------|
| [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Central manifest; defines all metadata and skill configuration |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.