# Versioning Requirements for Skill Files in Knowledge-Work-Plugins: A Complete Guide > Learn the essential versioning requirements for skill files in Knowledge-Work-Plugins. Understand semantic versioning (MAJOR.MINOR.PATCH) for flawless skill integration. - Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins) - Tags: how-to-guide - Published: 2026-05-25 --- **Every skill file in the Knowledge-Work-Plugins repository must declare a mandatory `version` field in its YAML front-matter following semantic versioning (`MAJOR.MINOR.PATCH`), and the runtime loader will reject any [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file that omits this field.** The `anthropics/knowledge-work-plugins` repository enforces strict versioning requirements for skill files to ensure compatibility and reliable dependency resolution across its plugin ecosystem. Each skill definition resides in a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file that must include a valid `version` field in its front-matter metadata. Understanding these versioning requirements for skill files is essential for contributors and runtime implementers working with the knowledge-work architecture. ## Semantic Versioning Structure for Skills All skill files must adhere to **semantic versioning** conventions to communicate compatibility and change impact clearly. ### The Mandatory `version` Field The `version` field is **mandatory** and appears within the **YAML front-matter** (the block enclosed by `---` at the top of each [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file). According to the repository's validation logic, if a skill file omits this field, the loader will reject the file during validation. The field typically appears as the third line in the front-matter block, following fields like `name` and `description`. Real-world examples from the repository include: - [`small-business/skills/lead-triage/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/lead-triage/SKILL.md) – version `0.1.1` - [`small-business/skills/invoice-chase/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/invoice-chase/SKILL.md) – version `0.2.0` - [`small-business/skills/customer-pulse/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/customer-pulse/SKILL.md) – version `0.2.0` ### Semver Component Rules The repository follows standard semantic versioning where each component signals specific types of changes: - **MAJOR** – Increment when introducing **breaking changes** to the skill's input, output schema, or behavior that would cause existing integrations to fail. - **MINOR** – Increment when adding **backwards-compatible features** or optional parameters that extend functionality without breaking existing usage. - **PATCH** – Increment for **bug fixes**, documentation updates, or internal corrections that do not alter the skill's contract or behavior. ## How to Declare Versions in SKILL.md Files Version declarations live in the YAML front-matter at the beginning of each skill file. The front-matter must start and end with triple dashes, with the `version` field specified using standard YAML key-value syntax. ```markdown --- name: lead-triage version: 0.1.1 description: > Automatically triages incoming leads based on priority scoring. --- # Lead Triage Skill [Skill content follows...] ``` For a new skill starting at version 1.0.0, the minimal front-matter structure would be: ```yaml --- name: my-awesome-skill version: 1.0.0 description: > Summarizes sales pipeline and suggests next steps. --- ``` ## Version Bump Guidelines and Examples When updating existing skills in `anthropics/knowledge-work-plugins`, you must increment the version appropriately based on the nature of your changes. ### Patch-Level Changes For documentation fixes or minor typos that don't affect functionality, increment the **PATCH** number. For example, if correcting a description in [`small-business/skills/lead-triage/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/lead-triage/SKILL.md): ```yaml --- version: 0.1.2 # Bumped from 0.1.1 for typo fix --- ``` Commit this change with a clear message: ```bash fix(lead-triage): correct description typo ``` ### Minor-Level Enhancements When adding backwards-compatible features or optional parameters, increment the **MINOR** number while resetting PATCH to zero. ### Major-Level Breaking Changes If you redesign the `lead-triage` scoring algorithm such that the output schema changes or existing integrations would break, you must perform a **MAJOR** version bump: ```yaml version: 1.0.0 # MAJOR bump – breaking change to output schema ``` This signals to dependent skills and runtimes that they must update their integration code before consuming this version. ## Validation and Runtime Enforcement The repository's runtime loader validates the `version` field during file ingestion. This validation occurs when the system processes skill files from paths such as [`small-business/skills/lead-triage/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/lead-triage/SKILL.md) or [`small-business/skills/invoice-chase/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/invoice-chase/SKILL.md). The version field enables: - **Compatibility tracking** – The runtime identifies which skill definition it is loading. - **Dependency resolution** – Other skills or plugins may reference specific version ranges, and the declared version enables the system to select the correct implementation. - **Change management** – Developers can determine upgrade safety by comparing version numbers. ## Summary - Every [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file must include a `version` field in its YAML front-matter using `MAJOR.MINOR.PATCH` format. - The runtime loader rejects skill files that omit the version field during validation. - Increment **MAJOR** for breaking changes, **MINOR** for backwards-compatible features, and **PATCH** for bug fixes or documentation updates. - Reference existing skills like [`small-business/skills/lead-triage/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/lead-triage/SKILL.md) (version `0.1.1`) and [`small-business/skills/invoice-chase/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/invoice-chase/SKILL.md) (version `0.2.0`) for implementation examples. ## Frequently Asked Questions ### What happens if a skill file doesn't include a version field? The runtime loader will reject the file during validation. The `version` field is mandatory for all skill files in the repository, and files lacking this field in their YAML front-matter cannot be loaded or executed by the knowledge-work system. ### Which skill files in the repository demonstrate proper versioning? The repository provides several canonical examples: [`small-business/skills/lead-triage/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/lead-triage/SKILL.md) demonstrates version `0.1.1`, while [`small-business/skills/invoice-chase/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/invoice-chase/SKILL.md) and [`small-business/skills/customer-pulse/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/customer-pulse/SKILL.md) both implement version `0.2.0`. These files show the standard YAML front-matter structure with proper semantic version declarations. ### How do I version a skill when fixing a documentation typo? Increment the **PATCH** number when making documentation fixes or corrections that don't alter the skill's behavior or contract. For example, change `version: 0.1.1` to `version: 0.1.2` and commit with a descriptive message like `fix(skill-name): correct description typo`. ### What version should I use for a complete redesign of a skill's output schema? Perform a **MAJOR** version bump when redesigning output schemas or making any breaking changes that would cause existing integrations to fail. For instance, if redesigning the `lead-triage` scoring algorithm changes the output format, update the version from `0.1.1` to `1.0.0` to signal the breaking change to dependent systems.