# How to Version Skills in Nutlope/Hallmark: A Complete Guide to Skill Releases

> Learn to version skills in Nutlope/hallmark by synchronizing version fields and creating Git tags.  Follow this complete guide for seamless skill releases.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-29

---

**To version skills in Nutlope/hallmark, you must synchronize the `version:` field in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) with the `"version"` field in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), then commit the changes and create a Git tag prefixed with `v`.**

The Nutlope/hallmark repository uses a dual-versioning scheme that requires maintaining version consistency across multiple files. When you version skills in Nutlope/hallmark correctly, you ensure that AI assistants report accurate version numbers and npm distributions remain synchronized with the source code. This guide walks through the exact files to modify and the automation scripts that streamline the release process.

## Understanding the Dual-Versioning System

Hallmark employs two distinct version trackers that must remain identical:

- **Skill metadata** ([`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)): Contains the `version:` field (currently `1.1.0` at line 4) that AI assistants display when running the skill.
- **Package manifest** ([`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)): Stores the npm package version (currently `"1.1.0"` at line 3) used for CLI distribution and publishing.

When these values drift out of sync, the skill appears outdated to users while CI pipelines may reference incorrect package versions.

## Step-by-Step Versioning Process

### Decide the Semantic Version

Follow SemVer (MAJOR.MINOR.PATCH) conventions:

- Increment **MAJOR** for breaking changes
- Increment **MINOR** for new features  
- Increment **PATCH** for bug fixes or documentation updates

### Update the Skill Metadata

Modify [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) to reflect the new version:

```diff
- version: 1.1.0
+ version: 1.2.0

```

This field appears at line 4 of the file and drives the version shown by the skill harness when users run `npx skills add`.

### Sync the Package Version

Update [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) to match exactly:

```diff
-   "version": "1.1.0",
+   "version": "1.2.0",

```

The `npm publish` command reads this value from line 3 when distributing the skill as a CLI tool.

### Commit and Tag the Release

Stage both files and create a Git tag:

```bash
git add skills/hallmark/SKILL.md package.json
git commit -m "chore: bump Hallmark skill to v1.2.0"
git tag -a v1.2.0 -m "Hallmark skill v1.2.0"
git push origin main --tags

```

Note the `v` prefix in the Git tag, which distinguishes release tags from branch names.

### Verify the Site Footer

The Hallmark site displays the current version in the footer at line 1091 of [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html). After deployment, verify the HTML reflects your update:

```html
<span class="foot__version tnum">v1.2 · MMXXVI</span>

```

## Automating Version Bumps with Node.js

Drop this script into [`scripts/bump-version.js`](https://github.com/Nutlope/hallmark/blob/main/scripts/bump-version.js) to automate the editing and tagging process:

```javascript
// scripts/bump-version.js
const fs = require('fs');
const path = require('path');
const execSync = require('child_process').execSync;

function bump(newVersion) {
  const skillPath = path.join(__dirname, '..', 'skills', 'hallmark', 'SKILL.md');
  const pkgPath   = path.join(__dirname, '..', 'package.json');

  // Update SKILL.md
  let skill = fs.readFileSync(skillPath, 'utf8');
  skill = skill.replace(/^version:\s*\d+\.\d+\.\d+/m, `version: ${newVersion}`);
  fs.writeFileSync(skillPath, skill);

  // Update package.json
  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
  pkg.version = newVersion;
  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');

  // Git commit & tag
  execSync('git add ' + skillPath + ' ' + pkgPath);
  execSync(`git commit -m "chore: bump Hallmark skill to v${newVersion}"`);
  execSync(`git tag -a v${newVersion} -m "Hallmark skill v${newVersion}"`);
  console.log(`✅ Bumped to ${newVersion}`);
}

// Usage: node scripts/bump-version.js 1.2.0
if (require.main === module) {
  const [, , newVer] = process.argv;
  if (!newVer) {
    console.error('Specify a version, e.g. node bump-version.js 1.2.0');
    process.exit(1);
  }
  bump(newVer);
}

```

Run the automation with:

```bash
node scripts/bump-version.js 1.2.0

```

This updates both version fields, commits the changes, and creates the annotated Git tag in a single command.

## Summary

- **Dual-versioning requirement**: Always update both [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (line 4) and [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) (line 3) to maintain consistency between skill metadata and npm packages.
- **Git tagging convention**: Use the `v` prefix (e.g., `v1.2.0`) when creating release tags to properly mark versions in the repository history.
- **Site synchronization**: The version displayed in [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) (line 1091) updates separately based on your deployment pipeline.
- **Automation recommended**: The provided Node.js script eliminates manual editing errors and ensures both files remain synchronized during releases.

## Frequently Asked Questions

### What happens if SKILL.md and package.json versions differ?

When the versions diverge, AI assistants may report one version while npm installs another, creating confusion for users and potential mismatches in CI/CD pipelines. The skill harness reads from [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) while package managers read from [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), so maintaining parity is essential for reproducible builds.

### Does Hallmark follow semantic versioning?

Yes, the repository adheres to SemVer (MAJOR.MINOR.PATCH). Increment the major version for breaking API changes, minor for backward-compatible features, and patch for bug fixes. Both the skill metadata and package version should follow this scheme simultaneously.

### Where does the version appear on the Hallmark site?

The version renders in the site footer within a `span` element using the class `foot__version tnum`. According to the source code at line 1091 of [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html), the display format is `v{version} · MMXXVI`, which updates after you deploy the built assets.

### How do I publish a new version to npm?

After updating both version files and creating the Git tag, run `npm publish` from the repository root. This command uses the `"version"` field from [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) to determine the npm package version. Ensure you have proper authentication configured and the version hasn't been published previously to avoid registry conflicts.