Управление версиями и итерациями навыков
Навыки развиваются по мере изменения требований. Правильное управление версиями позволяет сохранить существующую работу при внесении изменений и быстро откатиться при возникновении ошибок.
Соглашения о нумерации версий
Навыки используют семантическое версионирование в формате:MAJOR.MINOR.PATCH。
| Сегмент версии | Когда увеличивать | Пример |
|---|---|---|
| MAJOR | Несовместимые мажорные изменения (например, изменения формата входных данных) | 1.0.0 → 2.0.0 |
| MINOR | Новые возможности, но обратно совместимые | 1.0.0 → 1.1.0 |
| PATCH | Исправления ошибок, без влияния на функциональность | 1.0.0 → 1.0.1 |
Указание версии в SKILL.md
Пример
name: csv-analyzer
version: 1.2.0
description: Анализирует CSV-файлы и выводит статистическую сводку.
---
Управление версиями Skill с помощью Git
Git — лучший инструмент для управления версиями Skill; каждое изменение создаёт чёткую запись истории.
Пример
cd my-skill/
git init
git add .
git commit -m "feat: initial version v1.0.0"
# Зафиксировать новую версию после изменения Skill
git add SKILL.md
git commit -m "fix: исправить проблему с пробелом в обработке пути к файлу"
# Пометить стабильную версию
git tag v1.0.1
git tag v1.1.0 -m "Добавить функциональность пакетной обработки нескольких файлов"
Рекомендуемый формат сообщения коммита
| Префикс | Значение | Пример |
|---|---|---|
| feat: | Новая функция | feat: добавить поддержку вывода в Excel |
| fix: | Исправление ошибки | fix: исправить падение при работе с пустыми файлами |
| docs: | Обновление документации | docs: добавить описания параметров |
| refactor: | Рефакторинг кода (без изменения функциональности) | refactor: вынести логику очистки в отдельную функцию |
| perf: | Оптимизация производительности | perf: ускорение обработки больших файлов в 3 раза |
Ведение CHANGELOG в SKILL.md
Для навыков, которые будут использоваться другими, добавление журнала изменений в конце SKILL.md помогает пользователям понимать изменения в каждой версии.
## 版本历史 ### v1.2.0(2026-05-18) - 新增:支持 .xlsx 输入格式 - 优化:大文件(>10MB)处理速度提升 40% ### v1.1.0(2026-04-10) - 新增:--col 参数,支持只分析指定列 - 修复:列名包含空格时的解析错误 ### v1.0.0(2026-03-01) - 初始版本:支持 CSV 文件的基础统计分析
Миграция версий: обработка несовместимых изменений
Когда навык претерпевает ломающие изменения (например, изменение формата входных данных или удаление возможности), необходимо предоставить существующим пользователям чёткие рекомендации по миграции.
## 迁移指南:从 v1.x 升级到 v2.0 ### 主要变化 v2.0 修改了输出文件的命名规则,由原来的 `output.xlsx` 改为带日期的 `output_YYYYMMDD.xlsx`。 ### 受影响场景 如果你的工作流依赖固定的输出文件名,需要在使用时重命名文件,或使用 `--output` 参数指定文件名。 ### 迁移步骤 1. 更新 Skill 到 v2.0 2. 检查是否有依赖固定文件名的脚本或工作流 3. 如有,添加 `--output output.xlsx` 参数保持旧行为
Ломающие изменения должны быть полностью оценены на предмет влияния перед выпуском. Если затронуто много пользователей, рассмотрите возможность сохранения старого параметра и пометки его как "deprecated", чтобы дать пользователям переходный период, вместо того чтобы удалять его сразу.
Откат к предыдущей версии
Пример
git log --oneline
# Просмотреть все теги версий
git tag
# Откатиться к указанному тегу версии
git checkout v1.1.0
# Или откатиться к конкретному коммиту (по хешу коммита)
git checkout a3f7b2c
# Если нужно продолжить разработку с откатанной версии в качестве новой ветки
git checkout -b hotfix/v1.1.1 v1.1.0