# AI Skill Versioning Managing changes to [[AI Agent Skills]] over time: tracking versions, maintaining backward compatibility, handling deprecation, and communicating updates. The same discipline software applies to libraries and APIs, applied to prompt-based skills. ## Why versioning matters - Skills evolve as tools, conventions, and requirements change - Agents composing multiple skills ([[AI Skill Composability]]) can break when a dependency updates - Teams sharing skills ([[AI Skill Distribution]]) need to coordinate updates - Without versioning, "it worked yesterday" becomes the debugging experience ## What changes in a skill - **Prompt text**: refined instructions, new edge case handling - **Tool call patterns**: switching from one tool to another, adding new tool usage - **Metadata**: trigger conditions, description, dependencies - **Context assumptions**: vault structure, available tools, expected environment - **Breaking vs non-breaking**: adding a new section is safe; changing output format is breaking ## The software parallel | Software concept | Skill equivalent | |-----------------|------------------| | Semantic versioning (1.2.3) | Not standardized yet for skills | | CHANGELOG | Change history in skill file or commit log | | Deprecation warnings | No standard mechanism | | Lock files | No skill lock files exist yet | | Dependency resolution | Manual; no automated dependency management | | Breaking change detection | Manual review only | ## Current state - Skills are files; versioning is git-based (commit history) - No semantic versioning standard for skills - No automated compatibility checking - No deprecation notification mechanism - [[Claude Code Plugins]] add some structure (plugin.json with version field) but skill-level versioning is still informal ## What's needed - Skill version metadata in frontmatter - Changelog convention (inline or companion file) - Compatibility declarations (works with Claude Code >= X, requires skill Y >= Z) - Automated testing to detect breaking changes ([[AI Skill Testing]]) ## References - ## Related - [[AI Agent Skills]] - [[AI Skill Distribution]] - [[AI Skill Composability]] - [[AI Skill Portability]] - [[AI Skill Testing]] - [[AI Skill Supply Chain Security]] - [[Claude Code Plugins]] - [[Context Drift]]