Gestión de versiones e iteración de Skills
Skill evoluciona continuamente con los requisitos cambiantes. Una gestión de versiones razonable te permite no perder los resultados existentes al modificar y también te permite revertir rápidamente cuando algo sale mal.
Convención de números de versión
Skills utiliza versionado semántico (Semantic Versioning), con el formato:MAJOR.MINOR.PATCH。
| Segmento del número de versión | Cuándo incrementar | Ejemplo |
|---|---|---|
| MAJOR (versión principal) | Cambios importantes incompatibles (como cambios en el formato de entrada) | 1.0.0 → 2.0.0 |
| MINOR (versión menor) | Nuevas funciones, pero compatible con versiones anteriores | 1.0.0 → 1.1.0 |
| PATCH (revisión) | Corrección de errores, sin afectar la funcionalidad | 1.0.0 → 1.0.1 |
Declarar la versión en SKILL.md
Ejemplo
name: csv-analyzer
version: 1.2.0
description: Analizar archivos CSV y generar un resumen estadístico.
---
Usar Git para gestionar versiones de Skill
Git es la mejor herramienta para gestionar versiones de Skill; cada modificación puede formar un historial claro.
Ejemplo
cd my-skill/
git init
git add .
git commit -m feat: versión inicial v1.0.0
# Enviar una nueva versión después de modificar el Skill
git add SKILL.md
git commit -m fix: corregir el problema de espacios en el manejo de rutas de archivos
# Etiquetar la versión estable
git tag v1.0.1
git tag v1.1.0 -m Nueva función de procesamiento por lotes de múltiples archivos
Formato recomendado de mensajes de confirmación
| Prefijo | Significado | Ejemplo |
|---|---|---|
| feat: | Nueva función | feat: agregar soporte de salida Excel |
| fix: | Corrección de errores (Bug fix) | fix: corregir el fallo al procesar archivos vacíos |
| docs: | Actualización de documentación | docs: añadir descripción de parámetros |
| refactor: | Refactorización de código (sin cambios funcionales) | refactor: extraer la lógica de limpieza como función independiente |
| perf: | Optimización de rendimiento | perf: velocidad de procesamiento de archivos grandes mejorada 3 veces |
Mantener CHANGELOG en SKILL.md
Para Skills que serán utilizados por otros, adjuntar un registro de cambios al final de SKILL.md ayuda a los usuarios a comprender los cambios de cada versión.
## 版本历史 ### v1.2.0(2026-05-18) - 新增:支持 .xlsx 输入格式 - 优化:大文件(>10MB)处理速度提升 40% ### v1.1.0(2026-04-10) - 新增:--col 参数,支持只分析指定列 - 修复:列名包含空格时的解析错误 ### v1.0.0(2026-03-01) - 初始版本:支持 CSV 文件的基础统计分析
Migración de versiones: cómo manejar cambios incompatibles
Cuando un Skill sufre cambios incompatibles (como modificar el formato de entrada o eliminar una función), es necesario proporcionar a los usuarios existentes una guía de migración clara.
## 迁移指南:从 v1.x 升级到 v2.0 ### 主要变化 v2.0 修改了输出文件的命名规则,由原来的 `output.xlsx` 改为带日期的 `output_YYYYMMDD.xlsx`。 ### 受影响场景 如果你的工作流依赖固定的输出文件名,需要在使用时重命名文件,或使用 `--output` 参数指定文件名。 ### 迁移步骤 1. 更新 Skill 到 v2.0 2. 检查是否有依赖固定文件名的脚本或工作流 3. 如有,添加 `--output output.xlsx` 参数保持旧行为
Los cambios incompatibles deben evaluar su alcance de impacto antes de la publicación. Si hay muchos usuarios, se pueden conservar los parámetros antiguos marcándolos como "obsoletos" para dar a los usuarios un tiempo de transición, en lugar de eliminarlos directamente.
Revertir a una versión histórica
Ejemplo
git log --oneline
# Ver todas las etiquetas de versión
git tag
# Revertir a la etiqueta de versión especificada
git checkout v1.1.0
# O revertir a una confirmación específica (mediante el hash del commit)
git checkout a3f7b2c
# Si es necesario continuar el desarrollo desde la versión revertida como nueva rama
git checkout -b hotfix/v1.1.1 v1.1.0