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

To version skills in Nutlope/hallmark, you must synchronize the version: field in skills/hallmark/SKILL.md with the "version" field in 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): Contains the version: field (currently 1.1.0 at line 4) that AI assistants display when running the skill.
• Package manifest (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 to reflect the new version:

- 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 to match exactly:

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

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. After deployment, verify the HTML reflects your update:

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

Automating Version Bumps with Node.js

Drop this script into scripts/bump-version.js to automate the editing and tagging process:

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

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 (line 4) and 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 (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 while package managers read from 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, 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 to determine the npm package version. Ensure you have proper authentication configured and the version hasn't been published previously to avoid registry conflicts.

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