@basetis/skill-manager

CLI para gestionar skills de IA (prompts reutilizables) e instalarlas en múltiples herramientas de coding: Claude Code, Gemini CLI, Codex CLI, Cursor y Windsurf.

Las skills se almacenan en un repositorio GitLab centralizado ([email protected]:okr-ia/basetisskills.git) con un catálogo definido en manifest.yml. El CLI descarga las skills desde ese catálogo y las coloca en el formato y ruta correctos para cada herramienta.

Prerequisitos

• Node.js >= 24 — verifica con node --version
• Token de acceso personal de GitLab con scope read_package_registry en git.basetis.com

Setup para developer nuevo

La forma más rápida de instalar es ejecutar el script de setup:

bash <(curl -fsSL https://git.basetis.com/okr-ia/basetisskills/-/raw/main/cli/scripts/setup.sh)

El script te pedirá tu token personal de GitLab, configurará npm y instalará el CLI globalmente.

Generar el token de GitLab

1. Ve a git.basetis.com → Settings → Access Tokens
2. Crea un token con el scope: read_package_registry
3. Copia el token (empieza por glpat-...)

Instalación manual

Si prefieres configurarlo a mano, añade a tu ~/.npmrc:

@basetis:registry=https://git.basetis.com/api/v4/packages/npm/
//git.basetis.com/api/v4/packages/npm/:_authToken=TU_GITLAB_TOKEN

Y luego:

npm install -g @basetis/skill-manager

Verifica la instalación:

skill-manager --version
# 0.1.0

Primeros pasos

1. Configurar el repositorio de skills

skill-manager init

? Tipo de repositorio de skills: › GitLab
? URL base del servidor: › https://git.basetis.com
? Project ID (numérico) o ruta (grupo/repo): › okr-ia/basetisskills
? Token de acceso personal: › ****
? Rama del repositorio: › main
? Herramienta de IA por defecto: › Claude Code

✔ Conexión verificada correctamente.
✔ Configuración guardada correctamente.
  → ~/.skill-manager/config.json

2. Explorar el catálogo

skill-manager list

  User Skills
  ────────────────────────────────────────
  user/development/kotlin-jvm    v1.0.0
  user/development/react         v1.0.0

  Internal Skills
  ────────────────────────────────────────
  internal/global                v2.0.0

  External Skills
  ────────────────────────────────────────
  external/sector/pharma                    v1.0.0
  external/client/alexion                   v1.2.0  ← external/sector/pharma
  external/project/alexion-cockpit          v2.0.0  ← external/client/alexion

  Total: 5 skills

Filtrar por nombre:

skill-manager list --filter alexion

3. Instalar una skill

skill-manager install external/project/alexion-cockpit

✔ Cadena resuelta: 3 skill(s).

  Skills a instalar (en orden):
  ├─ external/sector/pharma v1.0.0
  ├─ external/client/alexion v1.2.0
  └─ external/project/alexion-cockpit v2.0.0

? ¿En qué herramientas quieres instalar? › Claude Code, Cursor
? ¿Dónde instalar las skills? › Global (solo para ti, en ~/)

✔ Instalada external/sector/pharma
✔ Instalada external/client/alexion
✔ Instalada external/project/alexion-cockpit

✔ 3 skill(s) instalada(s) en Claude Code y Cursor (personal)

Instalación directa sin prompts:

skill-manager install external/client/alexion --tool claude,windsurf --scope global

4. Ver estado de las skills instaladas

skill-manager status

  Claude Code
  ──────────────────────────────────────────────────
  [Global]
  external/sector/pharma              1.0.0   ✓ al día
  external/client/alexion             1.1.0   ⬆ 1.2.0 disponible
  external/project/alexion-cockpit    2.0.0   ✓ al día

5. Detectar skills recomendadas automáticamente

cd mi-proyecto-kotlin/
skill-manager detect

✔ Análisis completo.

  Skills recomendadas:

  internal/global v2.0.0
    → Skill base recomendada para todos los proyectos.
  user/development/kotlin-jvm v1.0.0
    → Detectado: kotlin, jvm, gradle en el proyecto.

? ¿Instalar las skills recomendadas? › Sí

Referencia de comandos

| Comando | Argumentos | Descripción | |---|---|---| | skill-manager init | — | Configura el repositorio de skills y herramienta por defecto | | skill-manager list | --filter <texto> | Lista skills del catálogo, agrupadas por sección | | skill-manager install <ruta> | --tool <herramienta> --scope <global\|project> | Instala una skill y toda su cadena de dependencias | | skill-manager status | — | Compara versiones instaladas vs catálogo para cada herramienta | | skill-manager detect | — | Analiza el proyecto actual y recomienda skills relevantes |

Opciones globales

| Opción | Descripción | |---|---| | --version, -V | Muestra la versión del CLI | | --help, -h | Muestra la ayuda general o de un comando |

Herramientas soportadas

| Herramienta | Personal (global) | Proyecto (local) | |---|---|---| | Claude Code | ~/.claude/skills/{path}/SKILL.md | .claude/skills/{path}/SKILL.md | | Gemini CLI | ~/.gemini/skills/{path}/SKILL.md | .agents/skills/{path}/SKILL.md | | Codex CLI | ~/.codex/{name}/SKILL.md | .agents/skills/{path}/SKILL.md | | Cursor | ~/.cursor/rules/{name}.mdc | .cursor/rules/{name}.mdc | | Windsurf | ~/.windsurf/global_rules.md (append) | .windsurf/rules/{name}.md |

Cómo añadir soporte para una nueva herramienta

1. Crea un nuevo archivo en src/adapters/<herramienta>.js exportando:

export const toolName = "mi-herramienta";
export const displayName = "Mi Herramienta";

export function getInstallPath(skillPath, scope) {
  // Devuelve la ruta donde se instalará el SKILL.md
}

export async function install(skillPath, skillContent, scope) {
  // Escribe el contenido en la ruta correcta
  // Transforma el formato si es necesario (como Cursor con .mdc)
}

export async function getInstalledSkills(scope) {
  // Devuelve [{ path, version }] leyendo los archivos instalados
}

2. Regístralo en src/adapters/index.js:

import * as miHerramienta from "./mi-herramienta.js";

const adapters = [claude, gemini, codex, cursor, windsurf, miHerramienta];

3. Añade la detección en detectInstalledTools() del mismo archivo.

4. Escribe tests en src/adapters/adapters.test.js siguiendo el patrón existente.

Cómo contribuir al catálogo de skills

Las skills se gestionan en el repositorio okr-ia/basetisskills.

Consulta el archivo CONTRIBUTING.md de ese repositorio para conocer:

• Estructura de carpetas y convenciones de naming
• Formato del manifest.yml
• Cómo escribir un SKILL.md con frontmatter válido
• Flujo de review y merge para nuevas skills
• Cómo usar parent y upstream para cadenas de herencia

Licencia

Uso interno Basetis.