# How to Release a New Version of Claude-Skills: The Complete Workflow

> Learn the complete workflow for releasing a new version of claude-skills. Update version.json, run update-docs.py, validate, commit, and push tags to automate your release.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Releasing a new version of claude-skills requires updating [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/version.json), running [`scripts/update-docs.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/update-docs.py) to recalculate artifact counts, validating skills and markdown, committing changes, and pushing a Git tag that triggers the automated release pipeline in [`.github/workflows/release.yml`](https://github.com/Jeffallan/claude-skills/blob/main/.github/workflows/release.yml).**

The **Jeffallan/claude-skills** repository follows a disciplined, validation-first approach to releasing a new version of claude-skills. The process ensures that documentation, skill definitions, and published assets remain synchronized through a combination of local scripts and automated CI/CD. This guide covers the end-to-end workflow from version bump to GitHub Release publication.

## Update the Version Number and Recompute Counts

Every release starts with [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/version.json), the central source of truth for the package version.

First, edit [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/version.json) to bump the version field (for example, from `0.4.2` to `0.4.3`):

```bash
jq '.version = "0.4.3"' version.json > version.tmp && mv version.tmp version.json

```

Next, run [`scripts/update-docs.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/update-docs.py) to recalculate the number of skills, workflows, and reference files. This script writes the new counts back to [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/version.json) and synchronizes documentation across [`README.md`](https://github.com/Jeffallan/claude-skills/blob/main/README.md), [`plugin.json`](https://github.com/Jeffallan/claude-skills/blob/main/plugin.json), and other files:

```bash

# Preview changes without applying them

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

# Apply the updates

python scripts/update-docs.py

```

## Draft the Changelog and Update Documentation

Accurate release notes are essential for the automated pipeline. Add a new section to [`CHANGELOG.md`](https://github.com/Jeffallan/claude-skills/blob/main/CHANGELOG.md) following the *Keep a Changelog* format:

```bash
cat >> CHANGELOG.md <<'EOF'

## [0.4.3] - 2026-02-16

### Added

- New skill "cli-developer" for building command-line tools.
- Workflow command `project/planning/impl-plan.yaml` updated.

### Changed

- Updated skill count to 66.

### Fixed

- Fixed broken markdown table in `docs/WORKFLOW_COMMANDS.md`.
EOF

```

Update human-readable reference tables for any new or modified content:

- Add new skills to [`SKILLS_GUIDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILLS_GUIDE.md) and relevant decision-tree files.
- Add new commands to [`docs/WORKFLOW_COMMANDS.md`](https://github.com/Jeffallan/claude-skills/blob/main/docs/WORKFLOW_COMMANDS.md) and update the command table in [`README.md`](https://github.com/Jeffallan/claude-skills/blob/main/README.md).

## Regenerate Assets and Validate Integrity

Generate the social preview image that appears on the GitHub repository front page and in release notes:

```bash
npm install --no-save puppeteer && node ./assets/capture-screenshot.js

```

This creates `assets/social-preview.png` from the template in [`assets/social-preview.html`](https://github.com/Jeffallan/claude-skills/blob/main/assets/social-preview.html).

Run the validation suite to ensure no broken content reaches production:

```bash

# Validate skill YAML front-matter, name constraints, and reference completeness

python scripts/validate-skills.py

# Validate markdown syntax (unclosed code fences, table separators, etc.)

python scripts/validate-markdown.py

```

Perform a final manual verification to catch any stale version strings:

```bash
grep -r "OLD_VERSION" --include="*.md" --include="*.json" --include="*.py" .

```

## Commit, Tag, and Trigger the Release Pipeline

Once validation passes, commit all changes and create an annotated tag:

```bash
git add .
git commit -m "Release v0.4.3"
git tag v0.4.3
git push --follow-tags

```

Pushing the tag `v0.4.3` automatically triggers the **release** job defined in [`.github/workflows/release.yml`](https://github.com/Jeffallan/claude-skills/blob/main/.github/workflows/release.yml). This pipeline:

1. Runs the validation jobs ([`validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/validate-skills.py) and [`validate-markdown.py`](https://github.com/Jeffallan/claude-skills/blob/main/validate-markdown.py)) as prerequisites.
2. Builds the documentation site and uploads it as a GitHub Pages artifact.
3. Deploys the site to GitHub Pages.
4. Extracts the release notes from the [`CHANGELOG.md`](https://github.com/Jeffallan/claude-skills/blob/main/CHANGELOG.md) section matching the tag version.
5. Creates a GitHub Release using `softprops/action-gh-release@v2` with the extracted notes and built assets.

## Summary

Releasing a new version of claude-skills follows a validation-first, documentation-as-code workflow:

- **Centralize version control** in [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/version.json) and propagate changes via [`scripts/update-docs.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/update-docs.py).
- **Maintain accurate metadata** by updating [`CHANGELOG.md`](https://github.com/Jeffallan/claude-skills/blob/main/CHANGELOG.md) and skill reference guides before tagging.
- **Validate rigorously** using [`validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/validate-skills.py) and [`validate-markdown.py`](https://github.com/Jeffallan/claude-skills/blob/main/validate-markdown.py) to prevent broken releases.
- **Automate publication** through [`.github/workflows/release.yml`](https://github.com/Jeffallan/claude-skills/blob/main/.github/workflows/release.yml), which triggers on Git tags and handles site deployment and GitHub Release creation.

## Frequently Asked Questions

### What triggers the automated release pipeline in claude-skills?

Pushing a Git tag that starts with `v` (for example, `v0.4.3`) triggers the workflow defined in [`.github/workflows/release.yml`](https://github.com/Jeffallan/claude-skills/blob/main/.github/workflows/release.yml). The pipeline validates the codebase, builds the documentation site, and creates a GitHub Release with notes extracted from [`CHANGELOG.md`](https://github.com/Jeffallan/claude-skills/blob/main/CHANGELOG.md).

### How does the update-docs.py script maintain consistency across files?

The [`scripts/update-docs.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/update-docs.py) script reads the version from [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/version.json), recalculates the current counts of skills and workflows, and writes these values back to [`version.json`](https://github.com/Jeffallan/claude-skills/blob/main/version.json). It then synchronizes these counts across [`README.md`](https://github.com/Jeffallan/claude-skills/blob/main/README.md), [`plugin.json`](https://github.com/Jeffallan/claude-skills/blob/main/plugin.json), and other documentation files to ensure all published metadata matches the actual repository contents.

### What validation checks run before a claude-skills release is published?

Two primary validation scripts run both locally and in CI: [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) checks YAML front-matter, skill name constraints, and reference completeness, while [`scripts/validate-markdown.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-markdown.py) verifies markdown syntax including unclosed code fences, table formatting, and HTML comment issues. The release workflow in [`.github/workflows/release.yml`](https://github.com/Jeffallan/claude-skills/blob/main/.github/workflows/release.yml) will not proceed to deployment if either validation fails.

### Where should I document new skills when preparing a release?

New skills must be added to [`SKILLS_GUIDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/SKILLS_GUIDE.md) and any relevant decision-tree documentation files. Additionally, update the command tables in [`README.md`](https://github.com/Jeffallan/claude-skills/blob/main/README.md) and [`docs/WORKFLOW_COMMANDS.md`](https://github.com/Jeffallan/claude-skills/blob/main/docs/WORKFLOW_COMMANDS.md) if the new skills introduce new workflow commands. Finally, run [`scripts/update-docs.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/update-docs.py) to regenerate the skill counts and synchronize these changes across all metadata files.