Versioning Requirements for Skill Files in Knowledge-Work-Plugins: A Complete Guide

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 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 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 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 – version 0.1.1
• small-business/skills/invoice-chase/SKILL.md – version 0.2.0
• 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.

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

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

---
version: 0.1.2  # Bumped from 0.1.1 for typo fix

---

Commit this change with a clear message:

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:

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 or 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 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 (version 0.1.1) and 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 demonstrates version 0.1.1, while small-business/skills/invoice-chase/SKILL.md and 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.

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