How to Version and Update Skills Over Time in the Anthropic Skills Repository

Skills are version-controlled as regular Git directories, allowing you to use semantic versioning, Git tags, and the built-in package_skill.py script to create reproducible releases.

To effectively version and update skills over time, you treat each skill folder as an independent software package within the anthropics/skills repository. The repository provides scaffolding tools and packaging scripts that convert Git-tracked directories into distributable .skill archives, enabling precise version management without enforcing rigid metadata schemas.

Understanding the Skill Structure

Every skill in the repository follows a standardized folder structure generated by skills/skill-creator/scripts/init_skill.py. When you initialize a new skill, the script creates:

• SKILL.md — The primary documentation and metadata file
• scripts/ — Executable scripts that implement the skill's functionality
• references/ — Documentation and reference materials
• assets/ — Binary files and static resources

Because these are standard directories tracked by Git, you can apply standard software versioning practices including branching strategies, pull requests, and release tags.

Step-by-Step Workflow to Version and Update Skills

1. Initialize a New Skill

Create the initial folder structure using the provided initialization script:

python skills/skill-creator/scripts/init_skill.py image-editor --path skills/image-editor

This generates the scaffold in skills/image-editor/ with a basic SKILL.md file.

2. Add a Version Identifier

The repository does not enforce a mandatory version field, but convention suggests adding a semantic version identifier to SKILL.md or a dedicated VERSION file. Most contributors use the pattern name-vX.Y.Z.

Add a version line to your SKILL.md:

sed -i '2i version: "1.0.0"' skills/image-editor/SKILL.md

Alternatively, some skills include version metadata within reference files, such as skills/mcp-builder/reference/node_mcp_server.md, which contains version: "1.0.0" to indicate compatibility.

3. Commit Changes to Git

Track your initial skill version with a descriptive commit message following conventional commit standards:

git add skills/image-editor/
git commit -m "feat(image-editor): initial release v1.0.0"

4. Tag the Release

Create an annotated Git tag to mark the specific commit as a release version:

git tag -a image-editor-v1.0.0 -m "Release image-editor v1.0.0"

Tags provide immutable references that can be checked out later, ensuring users can install specific versions even as development continues on the main branch.

5. Package the Skill

Use the packaging script to create a distributable .skill archive from the current state of the skill folder:

python skills/skill-creator/scripts/package_skill.py skills/image-editor

This produces dist/image-editor.skill, a validated archive containing exactly the files present at the time of packaging. The script performs validation checks before zipping to ensure the skill structure meets repository standards.

6. Distribute the Versioned Skill

Upload the generated .skill file to your distribution channel, marketplace, or private store. Users can then install specific versions by referencing the tagged release (e.g., image-editor-v1.0.0.skill).

Updating an Existing Skill

When you need to version and update skills that already exist in the repository, follow this branching workflow to maintain clean history:

Checkout and Branch

Start from the existing release tag to ensure a clean baseline:

git checkout image-editor-v1.0.0
git checkout -b image-editor-v1.1.0-update

Modify and Version Bump

Update scripts, references, or assets as needed. Then increment the version identifier in SKILL.md:

sed -i 's/version: "1.0.0"/version: "1.1.0"/' skills/image-editor/SKILL.md

Commit the changes with a descriptive message indicating the nature of the update:

git add skills/image-editor/
git commit -m "feat(image-editor): add PDF rotation support"

Release the Update

Merge the update branch to your main branch, then tag and package the new version:

git checkout main
git merge image-editor-v1.1.0-update
git tag -a image-editor-v1.1.0 -m "Release image-editor v1.1.0"
python skills/skill-creator/scripts/package_skill.py skills/image-editor

Automating Version Management with CI/CD

You can automate the packaging and distribution process using GitHub Actions or similar CI platforms. Configure your workflow to trigger on version tags matching the pattern *-v*:

# .github/workflows/package-skill.yml

name: Package Skill
on:
  push:
    tags:
      - '*-v*'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Extract skill name from tag
        run: |
          SKILL_NAME=$(echo "${GITHUB_REF##*/}" | cut -d'-' -f1)
          echo "SKILL_DIR=skills/${SKILL_NAME}" >> $GITHUB_ENV
      - name: Package skill
        run: python skills/skill-creator/scripts/package_skill.py "${SKILL_DIR}"
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: ${{ github.ref_name }}.skill
          path: dist/*.skill

This automation ensures that every tagged release produces a validated .skill artifact without manual intervention, reducing the risk of packaging errors during distribution.

Summary

• Skills are Git-tracked folders, allowing you to version and update skills using standard Git workflows including branching, committing, and tagging.
• Semantic versioning is implemented by convention through version strings in SKILL.md or dedicated VERSION files, combined with annotated Git tags (e.g., skill-name-v1.2.0).
• Use skills/skill-creator/scripts/package_skill.py to create distributable .skill archives that capture the exact state of a skill at a specific version.
• Automate releases using CI/CD pipelines triggered by version tags to ensure consistent packaging and distribution.

Frequently Asked Questions

Does the skills repository enforce a specific version format?

No, the repository does not enforce a mandatory version field or specific format in SKILL.md. Versioning is a convention built on top of Git. Most contributors follow semantic versioning (e.g., 1.2.0) and include it as free-form text in the skill description or a dedicated version: field, but the tooling itself does not validate this metadata.

How do I ensure users can install a specific older version of my skill?

Create an annotated Git tag for every release (e.g., git tag -a my-skill-v1.0.0 -m "Release v1.0.0"). Tags provide immutable references to specific commits. When packaging the skill, run scripts/package_skill.py immediately after checking out the desired tag. Distribute the resulting .skill file with the version number in its filename, allowing users to select specific releases.

Can I update a skill without creating a new version tag?

Yes, you can commit changes to a skill's folder at any time since skills are regular Git-tracked directories. However, without a tag, there is no stable reference point for users to install that specific state. For production use, it is recommended to tag every meaningful release so that the package_skill.py script can produce reproducible .skill archives tied to specific version numbers.

What happens if I modify a skill after packaging it?

The .skill file is a static archive created by scripts/package_skill.py at the moment you run the command. If you modify the skill folder after packaging, those changes are not reflected in the already-generated .skill file. To include new changes, you must bump the version (if following semantic versioning), commit the changes, create a new Git tag, and re-run the packaging script to generate a new .skill archive.

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