# How Version Management Works in the Claude-Skills Project

> Discover how the claude-skills project manages versions using a single version.json file. Learn how it syncs artifact counts and enforces consistency through CI validation.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: internals
- Published: 2026-02-19

---

**The claude-skills project centralizes version management through a single [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/version.json)** at the repository root. This JSON file maintains four critical fields:

```json
{
  "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`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/update-docs.py)** utility automates the synchronization between the actual repository state and [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/version.json). This Python script performs three critical functions:

**1. Automatic Count Recomputation**

The script scans the filesystem to calculate current artifact counts:

```bash
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`](https://github.com/Jeffallan/claude-skills/blob/main/version.json).

**2. Documentation Marker Replacement**

The script identifies HTML comment markers in markdown and HTML files (such as [`README.md`](https://github.com/Jeffallan/claude-skills/blob/main/README.md), [`QUICKSTART.md`](https://github.com/Jeffallan/claude-skills/blob/main/QUICKSTART.md), and [`ROADMAP.md`](https://github.com/Jeffallan/claude-skills/blob/main/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:

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

```

## CI Enforcement and Validation

To prevent manual editing errors, the repository employs **[`.github/workflows/validate.yml`](https://github.com/Jeffallan/claude-skills/blob/main/.github/workflows/validate.yml)** to enforce synchronization on every pull request. The workflow executes:

```yaml
- 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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md)** file contains the canonical release checklist that coordinates human and automated steps:

**Step 1: Update the version string**

Manually edit [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/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:

```bash

# 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`](https://github.com/Jeffallan/claude-skills/blob/main/version.json)** serves as the immutable source of truth for version numbers and repository statistics in `Jeffallan/claude-skills`.
- **[`scripts/update-docs.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/update-docs.py)** automates count recomputation and documentation synchronization through HTML comment markers.
- **[`.github/workflows/validate.yml`](https://github.com/Jeffallan/claude-skills/blob/main/.github/workflows/validate.yml)** enforces consistency via the `--check` flag, preventing merges when documentation drifts from [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/version.json).
- The release process requires manual version bumping in [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/.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`](https://github.com/Jeffallan/claude-skills/blob/main/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.