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

Releasing a new version of claude-skills requires updating version.json, running 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.

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, the central source of truth for the package version.

First, edit version.json to bump the version field (for example, from 0.4.2 to 0.4.3):

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

Next, run scripts/update-docs.py to recalculate the number of skills, workflows, and reference files. This script writes the new counts back to version.json and synchronizes documentation across README.md, plugin.json, and other files:

# 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 following the Keep a Changelog format:

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 and relevant decision-tree files.
• Add new commands to docs/WORKFLOW_COMMANDS.md and update the command table in README.md.

Regenerate Assets and Validate Integrity

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

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

This creates assets/social-preview.png from the template in assets/social-preview.html.

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

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

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:

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. This pipeline:

1. Runs the validation jobs (validate-skills.py and 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 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 and propagate changes via scripts/update-docs.py.
• Maintain accurate metadata by updating CHANGELOG.md and skill reference guides before tagging.
• Validate rigorously using validate-skills.py and validate-markdown.py to prevent broken releases.
• Automate publication through .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. The pipeline validates the codebase, builds the documentation site, and creates a GitHub Release with notes extracted from CHANGELOG.md.

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

The scripts/update-docs.py script reads the version from version.json, recalculates the current counts of skills and workflows, and writes these values back to version.json. It then synchronizes these counts across README.md, 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 checks YAML front-matter, skill name constraints, and reference completeness, while 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 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 and any relevant decision-tree documentation files. Additionally, update the command tables in README.md and docs/WORKFLOW_COMMANDS.md if the new skills introduce new workflow commands. Finally, run scripts/update-docs.py to regenerate the skill counts and synchronize these changes across all metadata files.

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