How Version Management Works in the Claude-Skills Project

The claude-skills project centralizes version management through a single version.json file that automatically synchronizes artifact counts across documentation and enforces consistency via CI validation.

Effective version management ensures that code, documentation, and release artifacts remain perfectly aligned. In the Jeffallan/claude-skills repository, this is achieved through a deterministic pipeline that treats version.json as the immutable source of truth for version numbers and repository statistics.

Centralized Version Storage in version.json

The foundation of the project's version management strategy resides in version.json at the repository root. This JSON file maintains four critical fields:

{
  "version": "0.4.7",
  "skillCount": 66,
  "workflowCount": 9,
  "referenceFileCount": 365
}

• version: The semantic version string used for releases and documentation badges.
• skillCount: Total number of skill directories in the repository.
• workflowCount: Number of workflow command files.
• referenceFileCount: Count of reference markdown files.

All documentation, CI pipelines, and plugin manifests read from this single file, eliminating the risk of version drift between different repository components.

Automated Synchronization with update-docs.py

The scripts/update-docs.py utility automates the synchronization between the actual repository state and version.json. This Python script performs three critical functions:

1. Automatic Count Recomputation

The script scans the filesystem to calculate current artifact counts:

python scripts/update-docs.py

It traverses skill directories, workflow files, and reference documentation to compute accurate statistics, then writes these values back to version.json.

2. Documentation Marker Replacement

The script identifies HTML comment markers in markdown and HTML files (such as README.md, QUICKSTART.md, and ROADMAP.md) and replaces content between them:

• <!-- SKILL_COUNT -->…<!-- /SKILL_COUNT -->
• <!-- WORKFLOW_COUNT -->…<!-- /WORKFLOW_COUNT -->
• <!-- REFERENCE_COUNT -->…<!-- /REFERENCE_COUNT -->

It also updates version badge URLs to reflect the current version string.

3. Dry-Run Capability

Preview changes without modifying files:

python scripts/update-docs.py --dry-run

CI Enforcement and Validation

To prevent manual editing errors, the repository employs .github/workflows/validate.yml to enforce synchronization on every pull request. The workflow executes:

- name: Check docs in sync
  run: python scripts/update-docs.py --check

The --check flag performs a read-only validation that exits with code 0 if all files match version.json, or fails with a non-zero exit code if discrepancies exist. This CI gate ensures that no PR can merge while documentation counts or version strings remain out of sync with the source of truth.

Release Workflow and Version Bumping

The CLAUDE.md file contains the canonical release checklist that coordinates human and automated steps:

Step 1: Update the version string

Manually edit version.json to increment the version number (e.g., "0.4.7" → "0.4.8").

Step 2: Synchronize the repository

Run the update script to propagate changes:

# Edit version.json first

vim version.json

# Then synchronize all documentation and counts

python scripts/update-docs.py

Step 3: Commit and verify

The CI pipeline automatically validates that all markers, badges, and count fields reflect the updated version before allowing merge.

Summary

• version.json serves as the immutable source of truth for version numbers and repository statistics in Jeffallan/claude-skills.
• scripts/update-docs.py automates count recomputation and documentation synchronization through HTML comment markers.
• .github/workflows/validate.yml enforces consistency via the --check flag, preventing merges when documentation drifts from version.json.
• The release process requires manual version bumping in version.json followed by automated synchronization to maintain perfect alignment across all artifacts.

Frequently Asked Questions

Where is the version number stored in claude-skills?

The version number is stored in version.json at the repository root. This file also contains computed counts for skills, workflows, and reference files, serving as the single source of truth for the entire project.

How do I update the version number and documentation counts?

First, manually edit the version field in version.json. Then run python scripts/update-docs.py to automatically recompute artifact counts and synchronize all documentation markers and version badges across markdown files.

What prevents version drift between code and documentation?

The .github/workflows/validate.yml CI workflow runs python scripts/update-docs.py --check on every pull request. This validation fails the build if any documentation markers or version strings differ from the values in version.json, enforcing synchronization before merge.

Can I preview documentation changes without modifying files?

Yes. Run python scripts/update-docs.py --dry-run to scan the repository and preview which files would be updated and what values would change, without actually writing modifications to disk.

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