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

> Learn to version and update skills in the anthropic/skills repository using Git and package_skill.py for reproducible releases. Master skill management effectively.

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

---

**Skills are version-controlled as regular Git directories, allowing you to use semantic versioning, Git tags, and the built-in [`package_skill.py`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/init_skill.py). When you initialize a new skill, the script creates:

- [`SKILL.md`](https://github.com/anthropics/skills/blob/main/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:

```bash
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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/SKILL.md) or a dedicated `VERSION` file. Most contributors use the pattern `name-vX.Y.Z`.

Add a version line to your [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md):

```bash
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`](https://github.com/anthropics/skills/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/anthropics/skills/blob/main/SKILL.md):

```bash
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:

```bash
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:

```bash
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*`:

```yaml

# .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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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.