@ariasbruno/skillbase 0.1.0

package/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+Guía operativa para agentes que trabajen en este repositorio.
+
+## Alcance
+Estas instrucciones aplican a todo el árbol del proyecto (`skillbase`).
+
+## Objetivo del proyecto
+`skillbase` es una CLI para gestionar skills locales/remotas:
+- store global por defecto: `~/.skillbase/skills`
+- skills en proyecto: `.agents/skills`
+- manifiesto del proyecto: `skillbase.json`
+
+## Reglas de implementación
+1. Mantener el código en JavaScript ESM (`"type": "module"`).
+2. Evitar dependencias externas salvo necesidad clara.
+3. Toda lógica de negocio va en `src/core.js`; `src/cli.js` sólo parsea/coordina comandos.
+4. Mantener mensajes de CLI en español (consistentes con README actual).
+5. Si agregas o cambias comandos, actualiza:
+   - ayuda en `src/cli.js`
+   - sección de comandos en `README.md`
+
+## Flujo de recomendaciones (init)
+- Usar integración propia (sin dependencias externas) para detectar stack.
+- Basarse en señales del proyecto (`package.json`, `requirements.txt`, etc).
+- Si cambias este comportamiento, documenta el motivo en README.
+
+## Migración
+- `skillbase migrate` migra desde `~/.agents/skills` a `~/.skillbase/skills`.
+- `skillbase migrate --project` migra desde `.agents/skills` del cwd al mismo destino global.
+- Mantener `--force` para sobrescritura explícita.
+
+## Calidad mínima
+Antes de cerrar cambios ejecutar:
+```bash
+npm run lint
+node bin/skillbase.js -h
+```
+
+## Publicación
+Si cambias comportamiento visible, actualiza README con ejemplos.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Arias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# 🧠 skillbase
+
+**Gestor de skills locales para entornos de desarrollo con IA.**
+
+`skillbase` es un CLI de Node.js que te permite administrar las skills de tus agentes de Inteligencia Artificial utilizando enlaces simbólicos (symlinks) o instalaciones locales por cada workspace, evitando la saturación del contexto.
+
+---
+
+## 🤔 El Problema: Saturación de Contexto (Context Bloat)
+
+Cuando desarrollas asistido por IA (usando herramientas como Cursor, Copilot o agentes personalizados), tener un directorio global con cientos de skills `.agents/skills/` destruye la precisión del modelo:
+
+*   **Alucinaciones:** El LLM se confunde al tener demasiadas herramientas irrelevantes a su disposición.
+*   **Consumo de Tokens:** Enviar el manifiesto de cientos de skills en cada prompt es lento y costoso.
+*   **Falta de foco:** Un proyecto no necesita las mismas skills que otro.
+
+## 💡 La Solución
+
+`skillbase` mantiene un **único registro global** en tu máquina (`~/.skillbase/skills`) y permite hacer una instalación en tu proyecto actual de **solo lo que necesitas**.
+
+Imagínate que estás trabajando en el frontend de un e-commerce. No necesitas que la IA vea herramientas de DevOps o Backend; solo necesitas tus skills de React y quizás algunas de SEO. Con `skillbase`, le das a tu agente exactamente ese contexto.
+
+---
+
+## 🚀 Instalación
+
+Instala el paquete globalmente:
+
+```bash
+npm install -g @ariasbruno/skillbase
+# O clona y linkea localmente:
+# npm link
+```
+
+## 💻 Uso Rápido (Quickstart)
+
+**1. Inicializa tu proyecto**
+Detecta tecnologías y sugiere skills compatibles:
+```bash
+skillbase init
+```
+
+**2. Añade las skills necesarias**
+```bash
+skillbase add seo-analyzer
+# O abre el selector interactivo:
+skillbase add
+```
+
+**3. Instala desde el manifiesto**
+Si ya tienes un `skillbase.json`, recrea el entorno:
+```bash
+skillbase install
+```
+
+---
+
+## 🛠️ Referencia de Comandos
+
+| Comando | Alias | Descripción |
+| :--- | :--- | :--- |
+| `skillbase ls` | `l` | Lista skills instaladas globalmente en `~/.skillbase/skills`. |
+| `skillbase init [--hard]` | | Detecta tecnologías y sugiere skills (usa `--hard` para analizar `tags` en `skill.json`). |
+| `skillbase add [<skill>] [-s]` | `a` | Instalar skill global. Sin nombre, abre el **selector interactivo**. `-s` crea symlink. |
+| `skillbase install` | `i` | Instala desde el manifiesto `skillbase.json`. Soporta `-r` (remotas) y `-f` (forzar). |
+| `skillbase install <ref> -r` | `i -r` | Instala skill remota (URL o GitHub). Requiere `-k <name>` si es un repo Git. |
+| `skillbase remove <skill> [--g]` | `rm` | Elimina skill del proyecto. Con `--g` la elimina del registro global. |
+| `skillbase check [-r]` | `c` | Busca actualizaciones. Con `-r` busca solo en fuentes remotas. |
+| `skillbase update [<skill>] [-r] [-f]` | `up` | Actualiza una o todas las skills. `-r` para remotas, `-f` para forzar. |
+| `skillbase migrate [-p] [-f]` | `m` | Migra desde el antiguo `.agents`. `-p` usa el dir del proyecto, `-f` sobrescribe. |
+
+### 🚩 Flags Detalladas
+- `-h`, `--help`: Muestra la ayuda detallada.
+- `-s`, `--sym`: Crea un enlace simbólico en lugar de copiar los archivos (útil para desarrollo).
+- `-r`, `--remote`: Indica que la operación debe consultar fuentes externas (GitHub o API de skills.sh).
+- `-f`, `--force`: Ignora errores de "ya existe" y sobrescribe archivos/configuraciones.
+- `-k`, `--skill`: Nombre de la skill específica a extraer cuando se instala desde un repositorio GitHub.
+- `-p`, `--project`: En migraciones, indica que el origen es `.agents/skills` del proyecto actual.
+- `--g`: Flag específica de `remove` para borrar una skill del registro global.
+
+### ⌨️ Aliases de comandos
+Para mayor velocidad, puedes usar las iniciales:
+`l` (ls), `a` (add), `i` (install), `rm` (remove), `c` (check), `up` (update), `m` (migrate).
+
+---
+
+## 📂 ¿Cómo funciona bajo el capó?
+
+`skillbase` organiza tus herramientas de forma eficiente:
+
+```text
+Tu Computadora
+├── ~/.skillbase/skills/           <-- (Tu registro global físico)
+│   ├── seo-analyzer/              <-- (Código fuente real)
+│   └── react-helper/
+│
+└── /Proyectos/mi-gran-app/        <-- (Tu workspace actual)
+    ├── skillbase.json             <-- (El manifiesto del proyecto)
+    └── .agents/skills/            <-- (Contexto limpio para la IA)
+        └── seo-analyzer/          <-- (Enlace o copia local)
+```
+
+Puedes cambiar la ubicación del registro global configurando la variable de entorno `SKILLBASE_HOME`.
+
+---
+
+## 🌐 Fuentes Remotas
+
+Instala skills directamente desde repositorios de GitHub:
+```bash
+skillbase install <repo-url> --remote
+# Ejemplo:
+skillbase install https://github.com/usuario/my-skills --remote --skill analyzer
+```
+
+---
+
+## 🤝 Contribuciones
+
+¡Las contribuciones son bienvenidas! Si tienes ideas para mejorar la gestión del contexto, abre un Issue o un Pull Request.
+
+## 📄 Licencia
+
+MIT

package/bin/skillbase.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCLI } from '../src/cli.js';
+
+runCLI(process.argv).catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ariasbruno/skillbase",
+  "version": "0.1.0",
+  "description": "CLI para administrar skills locales y remotas entre proyectos",
+  "type": "module",
+  "bin": {
+    "skillbase": "bin/skillbase.js"
+  },
+  "scripts": {
+    "start": "node bin/skillbase.js -h",
+    "lint": "node --check bin/skillbase.js && node --check src/cli.js && node --check src/core.js"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "skills",
+    "cli",
+    "agents",
+    "ai",
+    "context",
+    "bloat",
+    "developer-tools"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,253 @@
+import {
+  addSkillsInteractive,
+  addSkill,
+  checkUpdates,
+  getGlobalSkillsDir,
+  initProject,
+  installFromManifest,
+  installRemoteSkillRef,
+  listGlobalSkills,
+  migrateAgentsSkillsToSkillbase,
+  readManifest,
+  removeSkill,
+  updateSkills
+} from './core.js';
+
+function printHelp() {
+  console.log(`skillbase - Gestor de skills locales/remotas
+
+Uso:
+  skillbase -h
+  skillbase h
+  skillbase ls
+  skillbase l
+  skillbase init [--hard]
+  skillbase add <skill> [--sym]
+  skillbase add
+  skillbase a <skill> [-s]
+  skillbase install
+  skillbase i
+  skillbase install <skill|repo-url> --remote [--skill <name>] [--force]
+  skillbase remove <skill> [--g]
+  skillbase rm <skill> [--g]
+  skillbase check [--remote]
+  skillbase c [-r]
+  skillbase update [<skill>] [--remote] [--force]
+  skillbase up [<skill>] [-r] [-f]
+  skillbase migrate [--project] [--force]
+  skillbase m [--project] [-f]
+
+Descripción breve de comandos:
+  ls        Lista skills instaladas globalmente en ~/.skillbase/skills.
+  init      Sugiere skills globales según tecnologías del proyecto.
+  add       Instala una skill global (o abre selector interactivo sin argumentos).
+  install   Instala desde skillbase.json o una skill remota con --remote.
+  remove    Elimina una skill del proyecto o global con --g.
+  check     Revisa si hay versiones más nuevas disponibles.
+  update    Actualiza skills del manifiesto (todas o una puntual).
+  migrate   Migra skills desde .agents hacia ~/skillbase/skills.
+
+Aliases:
+  l=ls, h=-h, a=add, i=install, rm=remove, c=check, up=update, m=migrate
+
+Short flags:
+  -s=--sym, -r=--remote, -f=--force, -k=--skill, -p=--project
+
+Notas:
+  - Carpeta global por defecto: ~/.skillbase/skills
+  - Puedes cambiarla con SKILLBASE_HOME
+  - Las skills de proyecto viven en .agents/skills
+  - El manifiesto del proyecto es skillbase.json
+`);
+}
+
+function printCommandList() {
+  console.log(`Comandos disponibles:
+- skillbase ls
+- skillbase l
+- skillbase init [--hard]
+- skillbase add
+- skillbase add <skill> [--sym]
+- skillbase a <skill> [-s]
+- skillbase install | skillbase i
+- skillbase install <skill|repo-url> --remote [--skill <name>] [--force]
+- skillbase remove <skill> [--g]
+- skillbase rm <skill> [--g]
+- skillbase check [--remote]
+- skillbase c [-r]
+- skillbase update [<skill>] [--remote] [--force]
+- skillbase up [<skill>] [-r] [-f]
+- skillbase migrate [--project] [--force]
+- skillbase m [--project] [-f]
+
+Usa "skillbase -h" para ver detalles.`);
+}
+
+function hasFlag(args, ...flags) {
+  return args.some((arg) => flags.includes(arg));
+}
+
+function getFlagValue(args, ...flags) {
+  for (let i = 0; i < args.length; i += 1) {
+    if (flags.includes(args[i])) return args[i + 1] ?? null;
+  }
+  return null;
+}
+
+export async function runCLI(argv) {
+  const args = argv.slice(2);
+  const [rawCommand, maybeSkill] = args;
+  const commandAliases = {
+    h: '-h',
+    l: 'ls',
+    a: 'add',
+    i: 'install',
+    rm: 'remove',
+    c: 'check',
+    up: 'update',
+    m: 'migrate'
+  };
+  const command = commandAliases[rawCommand] ?? rawCommand;
+
+  if (!command) {
+    printCommandList();
+    return;
+  }
+
+  if (command === '-h' || command === '--help') {
+    printHelp();
+    return;
+  }
+
+  switch (command) {
+    case 'ls': {
+      const skills = await listGlobalSkills();
+      if (!skills.length) {
+        console.log(`No hay skills globales instaladas en ${getGlobalSkillsDir()}`);
+      } else {
+        console.log(`Skills globales (${getGlobalSkillsDir()}):`);
+        skills.forEach((skill) => console.log(`- ${skill}`));
+      }
+      return;
+    }
+
+    case 'init': {
+      const result = await initProject({ hard: hasFlag(args, '--hard') });
+      if (!result.technologies.length) {
+        console.log('No se detectaron tecnologías en el proyecto.');
+        return;
+      }
+      console.log(`Tecnologías detectadas: ${result.technologies.join(', ')}`);
+      if (!result.suggested.length) {
+        console.log('No se encontraron skills compatibles en ~/.skillbase/skills.');
+        return;
+      }
+      console.log(`Skills sugeridas: ${result.suggested.join(', ')}`);
+      if (result.cancelled) {
+        console.log('Selección cancelada.');
+        return;
+      }
+      if (result.installed.length) {
+        console.log(`Skills instaladas: ${result.installed.join(', ')}`);
+      } else {
+        console.log('No se seleccionaron skills para instalar.');
+      }
+      return;
+    }
+
+    case 'add': {
+      if (!maybeSkill) {
+        const result = await addSkillsInteractive({ sym: hasFlag(args, '--sym', '-s') });
+        if (result.cancelled) return;
+        if (!result.selected.length) {
+          console.log('No se seleccionaron skills para instalar.');
+          return;
+        }
+        console.log(`Skills instaladas: ${result.selected.join(', ')}`);
+        return;
+      }
+      await addSkill(maybeSkill, { sym: hasFlag(args, '--sym', '-s') });
+      console.log(`Skill "${maybeSkill}" instalada en el proyecto.`);
+      return;
+    }
+
+    case 'install': {
+      if (maybeSkill && hasFlag(args, '--remote', '-r')) {
+        await installRemoteSkillRef(maybeSkill, {
+          force: hasFlag(args, '--force', '-f'),
+          skill: getFlagValue(args, '--skill', '-k')
+        });
+        console.log(`Skill remota "${maybeSkill}" instalada.`);
+        return;
+      }
+      if (maybeSkill && !hasFlag(args, '--remote', '-r')) {
+        throw new Error('Para instalar una skill puntual usa "skillbase add <skill>" (global) o "skillbase install <skill|repo-url> --remote".');
+      }
+      await installFromManifest({ remote: hasFlag(args, '--remote', '-r'), force: hasFlag(args, '--force', '-f') });
+      const manifest = await readManifest();
+      console.log(`Instaladas ${manifest.skills.length} skills desde skillbase.json.`);
+      return;
+    }
+
+    case 'remove': {
+      if (!maybeSkill) throw new Error('Debes indicar una skill: skillbase remove <skill>');
+      await removeSkill(maybeSkill, { global: hasFlag(args, '--g') });
+      if (hasFlag(args, '--g')) {
+        console.log(`Skill global "${maybeSkill}" eliminada.`);
+      } else {
+        console.log(`Skill "${maybeSkill}" eliminada del proyecto.`);
+      }
+      return;
+    }
+
+    case 'check': {
+      const updates = await checkUpdates({ remoteOnly: hasFlag(args, '--remote', '-r') });
+      if (!updates.length) {
+        console.log('No hay actualizaciones disponibles.');
+        return;
+      }
+      console.log('Actualizaciones disponibles:');
+      updates.forEach((item) => {
+        console.log(`- ${item.name}: ${item.current ?? 'desconocida'} -> ${item.latest} (${item.source})`);
+      });
+      return;
+    }
+
+    case 'update': {
+      const skill = maybeSkill && !maybeSkill.startsWith('-') ? maybeSkill : null;
+      await updateSkills({
+        skillName: skill,
+        remoteOnly: hasFlag(args, '--remote', '-remote', '-r'),
+        force: hasFlag(args, '--force', '-f')
+      });
+      if (skill) {
+        console.log(`Skill "${skill}" actualizada.`);
+      } else {
+        console.log('Skills actualizadas.');
+      }
+      return;
+    }
+
+    case 'migrate': {
+      const fromProject = hasFlag(args, '--project', '-p');
+      const result = await migrateAgentsSkillsToSkillbase({
+        force: hasFlag(args, '--force', '-f'),
+        fromProject
+      });
+      console.log(`Origen de migración: ${result.sourceRoot}/skills`);
+      console.log(`Skills encontradas: ${result.totalFound}`);
+      if (result.migrated.length) {
+        console.log(`Migradas a ${getGlobalSkillsDir()}:`);
+        result.migrated.forEach((skill) => console.log(`- ${skill}`));
+      }
+      if (result.skipped.length) {
+        console.log('Omitidas (ya existen globalmente, usa --force para sobrescribir):');
+        result.skipped.forEach((skill) => console.log(`- ${skill}`));
+      }
+      return;
+    }
+
+    default:
+      throw new Error(`Comando desconocido: ${command}. Usa skillbase -h`);
+  }
+}

package/src/config.js

@@ -0,0 +1,29 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export const MANIFEST_FILE = 'skillbase.json';
+export const PROJECT_AGENTS_DIR = '.agents';
+export const PROJECT_SKILLS_DIR = 'skills';
+export const DEFAULT_GLOBAL_ROOTNAME = '.skillbase';
+
+export function getGlobalRootDir() {
+  const fromEnv = process.env.SKILLBASE_HOME;
+  if (fromEnv) return path.resolve(fromEnv);
+  return path.join(os.homedir(), DEFAULT_GLOBAL_ROOTNAME);
+}
+
+export function getGlobalSkillsDir() {
+  return path.join(getGlobalRootDir(), PROJECT_SKILLS_DIR);
+}
+
+export function getProjectRoot(cwd = process.cwd()) {
+  return cwd;
+}
+
+export function getProjectSkillsDir(cwd = process.cwd()) {
+  return path.join(getProjectRoot(cwd), PROJECT_AGENTS_DIR, PROJECT_SKILLS_DIR);
+}
+
+export function getManifestPath(cwd = process.cwd()) {
+  return path.join(getProjectRoot(cwd), MANIFEST_FILE);
+}

package/src/core.js

@@ -0,0 +1,581 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import * as readline from 'node:readline';
+import { stdin as input, stdout as output } from 'node:process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { getGlobalSkillsDir, getProjectRoot, getProjectSkillsDir, PROJECT_AGENTS_DIR, PROJECT_SKILLS_DIR } from './config.js';
+import { readManifest, removeSkillFromManifest, upsertSkill, writeJson, writeManifest } from './manifest.js';
+import { detectProjectTechnologies } from './recommendations.js';
+const execFileAsync = promisify(execFile);
+
+function nowISO() {
+  return new Date().toISOString();
+}
+
+export { getGlobalSkillsDir, getProjectRoot, getProjectSkillsDir, readManifest };
+
+export async function ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function listGlobalSkills() {
+  const globalDir = getGlobalSkillsDir();
+  await ensureDir(globalDir);
+  const entries = await fs.readdir(globalDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+
+async function copyDir(src, dst) {
+  await fs.cp(src, dst, { recursive: true, force: true });
+}
+
+async function readSkillVersion(skillPath) {
+  const skillMeta = path.join(skillPath, 'skill.json');
+  if (!(await exists(skillMeta))) return null;
+  const data = JSON.parse(await fs.readFile(skillMeta, 'utf8'));
+  return typeof data.version === 'string' ? data.version : null;
+}
+
+function compareVersion(a, b) {
+  if (!a || !b) return 0;
+  const aa = a.split('.').map((x) => Number.parseInt(x, 10) || 0);
+  const bb = b.split('.').map((x) => Number.parseInt(x, 10) || 0);
+  for (let i = 0; i < Math.max(aa.length, bb.length); i += 1) {
+    const av = aa[i] ?? 0;
+    const bv = bb[i] ?? 0;
+    if (av > bv) return 1;
+    if (av < bv) return -1;
+  }
+  return 0;
+}
+
+export async function addSkill(skillName, { sym = false, cwd = process.cwd() } = {}) {
+  const globalPath = path.join(getGlobalSkillsDir(), skillName);
+  if (!(await exists(globalPath))) {
+    throw new Error(`La skill global "${skillName}" no existe en ${getGlobalSkillsDir()}`);
+  }
+
+  const projectSkillsDir = getProjectSkillsDir(cwd);
+  await ensureDir(projectSkillsDir);
+  const target = path.join(projectSkillsDir, skillName);
+
+  if (await exists(target)) {
+    await fs.rm(target, { recursive: true, force: true });
+  }
+
+  if (sym) await fs.symlink(globalPath, target, 'dir');
+  else await copyDir(globalPath, target);
+
+  const manifest = await readManifest(cwd);
+  const version = await readSkillVersion(globalPath);
+  upsertSkill(manifest, {
+    name: skillName,
+    source: 'global',
+    linked: sym,
+    version,
+    installedAt: nowISO()
+  });
+  await writeManifest(manifest, cwd);
+}
+
+export async function addSkillsInteractive({ cwd = process.cwd(), sym = false } = {}) {
+  const skills = await listGlobalSkills();
+  if (!skills.length) return { selected: [], cancelled: false };
+  const selection = await selectSkillsFromList(skills, {
+    title: 'Selecciona skills para instalar',
+    requireTTYMessage: 'La selección interactiva requiere una terminal TTY. Usa: skillbase add <skill>.'
+  });
+  if (selection.cancelled) return { selected: [], cancelled: true };
+  const selectedSkills = selection.selected;
+  for (const skill of selectedSkills) {
+    await addSkill(skill, { cwd, sym });
+  }
+  output.write(`\nInstaladas: ${selectedSkills.join(', ') || 'ninguna'}\n`);
+  return { selected: selectedSkills, cancelled: false };
+}
+
+async function selectSkillsFromList(skills, { title, requireTTYMessage } = {}) {
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error(requireTTYMessage || 'La selección interactiva requiere una terminal TTY.');
+  }
+
+  const selected = new Set();
+  let cursor = 0;
+  let offset = 0;
+  let renderedLines = 0;
+  let firstRender = true;
+
+  // Tamaño de página adaptativo (mínimo 5, máximo 15 por defecto)
+  const getPageSize = () => {
+    const terminalRows = output.rows || 24;
+    const reservedRows = 8; // Header (5) + Footer (2) + Margen (1)
+    return Math.max(5, Math.min(15, terminalRows - reservedRows));
+  };
+
+  readline.emitKeypressEvents(input);
+  input.resume();
+  if (typeof input.setRawMode === 'function') input.setRawMode(true);
+
+  const render = () => {
+    const pageSize = getPageSize();
+    
+    // Ajustar ventana (offset) según el cursor
+    if (cursor < offset) {
+      offset = cursor;
+    } else if (cursor >= offset + pageSize) {
+      offset = cursor - pageSize + 1;
+    }
+
+    const lines = [
+      '\x1b[36m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\x1b[0m',
+      `\x1b[1m${title || 'Selecciona skills'}\x1b[0m`,
+      '\x1b[2m↑/↓ navegar · espacio seleccionar · enter confirmar · esc cancelar\x1b[0m',
+      '\x1b[36m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\x1b[0m',
+      ''
+    ];
+
+    // Indicador superior si hay más arriba
+    if (offset > 0) {
+      lines.push('\x1b[2m  ▲  y más...\x1b[0m');
+    } else {
+      lines.push('');
+    }
+
+    const visibleSkills = skills.slice(offset, offset + pageSize);
+    visibleSkills.forEach((skill, index) => {
+      const realIndex = index + offset;
+      const isSelected = selected.has(skill);
+      const isCursor = realIndex === cursor;
+      const mark = isSelected ? '[x]' : '[ ]';
+      const pointer = isCursor ? '\x1b[32m❯\x1b[0m' : ' ';
+      const line = `${mark} ${skill}`;
+      lines.push(isCursor ? `${pointer} \x1b[1m${line}\x1b[0m` : `${pointer} ${line}`);
+    });
+
+    // Rellenar hasta pageSize para mantener altura constante (evita parpadeos)
+    for (let i = visibleSkills.length; i < pageSize; i += 1) {
+      lines.push('');
+    }
+
+    // Indicador inferior si hay más abajo
+    if (offset + pageSize < skills.length) {
+      lines.push('\x1b[2m  ▼  y más...\x1b[0m');
+    } else {
+      lines.push('');
+    }
+
+    if (!firstRender) {
+      readline.moveCursor(output, 0, -renderedLines);
+    }
+
+    for (let i = 0; i < lines.length; i += 1) {
+      readline.clearLine(output, 0);
+      readline.cursorTo(output, 0);
+      output.write(lines[i]);
+      if (i < lines.length - 1) output.write('\n');
+    }
+
+    // Limpiar líneas residuales si el tamaño de renderizado cambió (vía redimensionado de terminal)
+    if (!firstRender && renderedLines > lines.length) {
+      for (let i = lines.length; i < renderedLines; i += 1) {
+        output.write('\n');
+        readline.clearLine(output, 0);
+      }
+    }
+
+    output.write('\n');
+    renderedLines = lines.length + 1;
+    firstRender = false;
+  };
+
+  render();
+  let onKeypress;
+  const outcome = await new Promise((resolve) => {
+    onKeypress = (_, key) => {
+      if (key.name === 'up') {
+        cursor = (cursor - 1 + skills.length) % skills.length;
+        render();
+        return;
+      }
+      if (key.name === 'down') {
+        cursor = (cursor + 1) % skills.length;
+        render();
+        return;
+      }
+      if (key.name === 'space') {
+        const skill = skills[cursor];
+        if (selected.has(skill)) selected.delete(skill);
+        else selected.add(skill);
+        render();
+        return;
+      }
+      if (key.name === 'return' || key.name === 'enter') {
+        resolve({ cancelled: false });
+        return;
+      }
+      if (key.name === 'escape' || (key.name === 'c' && key.ctrl)) {
+        resolve({ cancelled: true });
+      }
+    };
+    input.on('keypress', onKeypress);
+  });
+
+  if (onKeypress) input.off('keypress', onKeypress);
+  if (typeof input.setRawMode === 'function') input.setRawMode(false);
+  input.pause();
+  output.write('\n');
+
+  if (outcome.cancelled) {
+    output.write('\nSelección cancelada.\n');
+    return { selected: [], cancelled: true };
+  }
+
+  return { selected: Array.from(selected), cancelled: false };
+}
+
+async function tryFetchJson(url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json();
+}
+
+function parseRemoteSkillRef(skillRef) {
+  const trimmed = skillRef.trim();
+  if (!trimmed) return { canonicalName: '', lookupKeys: [] };
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    try {
+      const url = new URL(trimmed);
+      const parts = url.pathname.split('/').filter(Boolean);
+      // Formato esperado en skills.sh: /<owner>/skills/<skill>
+      const skillIdx = parts.indexOf('skills');
+      if (skillIdx > 0 && parts[skillIdx + 1]) {
+        const owner = parts[skillIdx - 1];
+        const name = parts[skillIdx + 1];
+        const scoped = `${owner}/${name}`;
+        return { canonicalName: scoped, lookupKeys: [scoped, name] };
+      }
+      const last = parts.at(-1) ?? trimmed;
+      return { canonicalName: last, lookupKeys: [last] };
+    } catch {
+      return { canonicalName: trimmed, lookupKeys: [trimmed] };
+    }
+  }
+
+  return { canonicalName: trimmed, lookupKeys: [trimmed] };
+}
+
+async function fetchRemoteMetadata(skillRef) {
+  const parsed = parseRemoteSkillRef(skillRef);
+  if (!parsed.lookupKeys.length) {
+    throw new Error('Debes indicar una skill remota válida.');
+  }
+
+  for (const key of parsed.lookupKeys) {
+    const encoded = encodeURIComponent(key);
+    const escapedPath = key.split('/').map(encodeURIComponent).join('/');
+    const candidates = [
+      `https://skills.sh/api/skills/${encoded}.json`,
+      `https://skills.sh/${escapedPath}/skill.json`,
+      `https://skills.sh/${escapedPath}/skills/${encodeURIComponent(parsed.canonicalName.split('/').at(-1) ?? key)}/skill.json`
+    ];
+
+    for (const url of candidates) {
+      try {
+        const data = await tryFetchJson(url);
+        return { ...data, _fetchedFrom: url, _resolvedName: parsed.canonicalName };
+      } catch {
+        // next
+      }
+    }
+  }
+
+  throw new Error(
+    `No se pudo obtener metadata remota para "${skillRef}". Usa slug tipo "owner/skill" o URL de skills.sh.`
+  );
+}
+
+async function downloadSkillFromRemote(skillRef, tmpDir) {
+  const metadata = await fetchRemoteMetadata(skillRef);
+  const resolvedName = metadata._resolvedName || skillRef;
+  const localName = resolvedName.split('/').at(-1) || resolvedName;
+  const sourceUrl = metadata.downloadUrl || metadata.sourceUrl || metadata.repo || metadata.url;
+
+  if (!sourceUrl) {
+    throw new Error(`La metadata remota de "${skillRef}" no contiene downloadUrl/sourceUrl/repo/url`);
+  }
+
+  if (metadata.archiveUrl) {
+    const archiveResponse = await fetch(metadata.archiveUrl);
+    if (!archiveResponse.ok) throw new Error(`No se pudo descargar archiveUrl (${archiveResponse.status})`);
+    const archivePath = path.join(tmpDir, `${localName}.tgz`);
+    const buffer = Buffer.from(await archiveResponse.arrayBuffer());
+    await fs.writeFile(archivePath, buffer);
+    throw new Error('archiveUrl descargado, pero falta extractor .tgz (pendiente de implementación)');
+  }
+
+  const skillPath = path.join(tmpDir, localName);
+  await ensureDir(skillPath);
+  await writeJson(path.join(skillPath, 'skill.json'), {
+    name: resolvedName,
+    version: metadata.version ?? '0.0.0',
+    sourceUrl,
+    fetchedFrom: metadata._fetchedFrom
+  });
+  return { path: skillPath, metadata, localName, resolvedName };
+}
+
+export async function installRemoteSkill(skillName, { cwd = process.cwd(), force = false } = {}) {
+  const projectSkillsDir = getProjectSkillsDir(cwd);
+  await ensureDir(projectSkillsDir);
+
+  if (/^https?:\/\/github\.com\//i.test(skillName)) {
+    throw new Error('Para instalar desde GitHub usa: skillbase install <repo-url> --remote --skill <nombre-skill>.');
+  }
+
+  const tempBase = await fs.mkdtemp(path.join(os.tmpdir(), 'skillbase-'));
+  try {
+    const downloaded = await downloadSkillFromRemote(skillName, tempBase);
+    const target = path.join(projectSkillsDir, downloaded.localName);
+    if ((await exists(target)) && !force) {
+      throw new Error(`La skill "${downloaded.localName}" ya existe en el proyecto. Usa --force para reinstalar.`);
+    }
+    if (await exists(target)) await fs.rm(target, { recursive: true, force: true });
+    await copyDir(downloaded.path, target);
+
+    const manifest = await readManifest(cwd);
+    upsertSkill(manifest, {
+      name: downloaded.resolvedName,
+      localName: downloaded.localName,
+      source: 'remote',
+      linked: false,
+      version: downloaded.metadata.version ?? '0.0.0',
+      remoteUrl: downloaded.metadata.sourceUrl || downloaded.metadata.repo || downloaded.metadata.url || null,
+      installedAt: nowISO()
+    });
+    await writeManifest(manifest, cwd);
+  } finally {
+    await fs.rm(tempBase, { recursive: true, force: true });
+  }
+}
+
+async function installRemoteFromGitHub(repoUrl, selectedSkill, { cwd = process.cwd(), force = false } = {}) {
+  if (!selectedSkill) {
+    throw new Error('Falta --skill <nombre>. Ejemplo: skillbase install <repo-url> --remote --skill find-skills');
+  }
+
+  const projectSkillsDir = getProjectSkillsDir(cwd);
+  await ensureDir(projectSkillsDir);
+
+  const tempBase = await fs.mkdtemp(path.join(os.tmpdir(), 'skillbase-git-'));
+  const repoPath = path.join(tempBase, 'repo');
+  try {
+    await execFileAsync('git', ['clone', '--depth', '1', repoUrl, repoPath], { maxBuffer: 1024 * 1024 * 10 });
+    const candidates = [path.join(repoPath, 'skills', selectedSkill), path.join(repoPath, selectedSkill)];
+    let sourcePath = null;
+    for (const candidate of candidates) {
+      if (await exists(candidate)) {
+        sourcePath = candidate;
+        break;
+      }
+    }
+    if (!sourcePath) {
+      throw new Error(`No se encontró la skill "${selectedSkill}" en el repo remoto.`);
+    }
+
+    const target = path.join(projectSkillsDir, selectedSkill);
+    if ((await exists(target)) && !force) {
+      throw new Error(`La skill "${selectedSkill}" ya existe en el proyecto. Usa --force para reinstalar.`);
+    }
+    if (await exists(target)) await fs.rm(target, { recursive: true, force: true });
+    await copyDir(sourcePath, target);
+
+    const manifest = await readManifest(cwd);
+    const version = await readSkillVersion(sourcePath);
+    upsertSkill(manifest, {
+      name: selectedSkill,
+      source: 'remote',
+      linked: false,
+      version: version ?? '0.0.0',
+      remoteUrl: repoUrl,
+      installedAt: nowISO()
+    });
+    await writeManifest(manifest, cwd);
+  } finally {
+    await fs.rm(tempBase, { recursive: true, force: true });
+  }
+}
+
+export async function installRemoteSkillRef(skillRef, options = {}) {
+  if (/^https?:\/\/github\.com\//i.test(skillRef)) {
+    return installRemoteFromGitHub(skillRef, options.skill, options);
+  }
+  return installRemoteSkill(skillRef, options);
+}
+
+export async function installFromManifest({ cwd = process.cwd(), remote = false, force = false } = {}) {
+  const manifest = await readManifest(cwd);
+  if (!manifest.skills.length) {
+    throw new Error('No hay skills en skillbase.json. Usa "skillbase add <skill>" o "skillbase install <skill> --remote".');
+  }
+  for (const skill of manifest.skills) {
+    if (remote || skill.source === 'remote') await installRemoteSkill(skill.name, { cwd, force });
+    else await addSkill(skill.name, { cwd, sym: Boolean(skill.linked) });
+  }
+}
+
+export async function removeSkill(skillName, { cwd = process.cwd(), global = false } = {}) {
+  if (global) {
+    await fs.rm(path.join(getGlobalSkillsDir(), skillName), { recursive: true, force: true });
+    return;
+  }
+
+  await fs.rm(path.join(getProjectSkillsDir(cwd), skillName), { recursive: true, force: true });
+  const manifest = await readManifest(cwd);
+  removeSkillFromManifest(manifest, skillName);
+  await writeManifest(manifest, cwd);
+}
+
+async function getRemoteVersion(skillName) {
+  const metadata = await fetchRemoteMetadata(skillName);
+  return metadata.version ?? null;
+}
+
+export async function checkUpdates({ cwd = process.cwd(), remoteOnly = false } = {}) {
+  const manifest = await readManifest(cwd);
+  const updates = [];
+
+  for (const skill of manifest.skills) {
+    if (remoteOnly && skill.source !== 'remote') continue;
+
+    if (skill.source === 'remote') {
+      const latest = await getRemoteVersion(skill.name);
+      if (latest && compareVersion(latest, skill.version) > 0) {
+        updates.push({ name: skill.name, current: skill.version, latest, source: 'remote' });
+      }
+      continue;
+    }
+
+    const globalPath = path.join(getGlobalSkillsDir(), skill.name);
+    if (!(await exists(globalPath))) continue;
+    const latest = await readSkillVersion(globalPath);
+    if (latest && compareVersion(latest, skill.version) > 0) {
+      updates.push({ name: skill.name, current: skill.version, latest, source: 'global' });
+    }
+  }
+
+  return updates;
+}
+
+export async function updateSkills({ cwd = process.cwd(), skillName = null, remoteOnly = false } = {}) {
+  const manifest = await readManifest(cwd);
+  const selected = manifest.skills.filter((skill) => {
+    if (skillName && skill.name !== skillName) return false;
+    if (remoteOnly && skill.source !== 'remote') return false;
+    return true;
+  });
+
+  for (const skill of selected) {
+    if (skill.source === 'remote') {
+      await installRemoteSkill(skill.name, { cwd, force: true });
+    } else {
+      await addSkill(skill.name, { cwd, sym: Boolean(skill.linked) });
+      const globalVersion = await readSkillVersion(path.join(getGlobalSkillsDir(), skill.name));
+      const nextManifest = await readManifest(cwd);
+      upsertSkill(nextManifest, { ...skill, version: globalVersion || skill.version, installedAt: nowISO() });
+      await writeManifest(nextManifest, cwd);
+    }
+  }
+}
+
+async function getSkillTags(skillDir) {
+  const metaPath = path.join(skillDir, 'skill.json');
+  if (!(await exists(metaPath))) return [];
+  try {
+    const meta = JSON.parse(await fs.readFile(metaPath, 'utf8'));
+    if (Array.isArray(meta.tags)) return meta.tags.map((tag) => String(tag).toLowerCase());
+    if (typeof meta.tags === 'string') return meta.tags.split(',').map((tag) => tag.trim().toLowerCase()).filter(Boolean);
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+export async function initProject({ cwd = process.cwd(), hard = false } = {}) {
+  const technologies = await detectProjectTechnologies(cwd, { hard });
+  if (!technologies.length) return { technologies: [], suggested: [], installed: [], cancelled: false };
+
+  const globalSkills = await listGlobalSkills();
+  const suggested = [];
+  for (const skill of globalSkills) {
+    const skillLower = skill.toLowerCase();
+    const matchesByName = technologies.some((tech) => skillLower.includes(tech));
+    if (matchesByName) {
+      suggested.push(skill);
+      continue;
+    }
+    if (!hard) continue;
+    const tags = await getSkillTags(path.join(getGlobalSkillsDir(), skill));
+    if (tags.some((tag) => technologies.some((tech) => tag.includes(tech)))) {
+      suggested.push(skill);
+    }
+  }
+
+  if (!suggested.length) return { technologies, suggested: [], installed: [], cancelled: false };
+
+  const selection = await selectSkillsFromList(suggested, {
+    title: hard
+      ? 'Init --hard: selecciona skills recomendadas por nombre y tags'
+      : 'Init: selecciona skills recomendadas por nombre'
+  });
+  if (selection.cancelled) return { technologies, suggested, installed: [], cancelled: true };
+
+  for (const skill of selection.selected) {
+    await addSkill(skill, { cwd, sym: false });
+  }
+
+  return { technologies, suggested, installed: selection.selected, cancelled: false };
+}
+
+export async function migrateAgentsSkillsToSkillbase({ cwd = process.cwd(), force = false, fromProject = false } = {}) {
+  const globalDir = getGlobalSkillsDir();
+  await ensureDir(globalDir);
+
+  const agentsDir = fromProject ? path.join(getProjectRoot(cwd), PROJECT_AGENTS_DIR) : path.join(os.homedir(), '.agents');
+  const agentsSkillsDir = path.join(agentsDir, PROJECT_SKILLS_DIR);
+  const toMigrate = new Map();
+
+  if (await exists(agentsSkillsDir)) {
+    const entries = await fs.readdir(agentsSkillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) toMigrate.set(entry.name, path.join(agentsSkillsDir, entry.name));
+    }
+  }
+
+  const migrated = [];
+  const skipped = [];
+
+  for (const [skillName, sourcePath] of toMigrate.entries()) {
+    const targetPath = path.join(globalDir, skillName);
+    if ((await exists(targetPath)) && !force) {
+      skipped.push(skillName);
+      continue;
+    }
+    if (await exists(targetPath)) await fs.rm(targetPath, { recursive: true, force: true });
+    await copyDir(sourcePath, targetPath);
+    migrated.push(skillName);
+  }
+
+  return { migrated, skipped, totalFound: toMigrate.size, sourceRoot: agentsDir };
+}

package/src/manifest.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs/promises';
+import { getManifestPath } from './config.js';
+
+async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function safeReadJson(file, fallback) {
+  if (!(await exists(file))) return fallback;
+  const raw = await fs.readFile(file, 'utf8');
+  return JSON.parse(raw);
+}
+
+export async function writeJson(file, data) {
+  await fs.writeFile(file, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+export async function readManifest(cwd = process.cwd()) {
+  const manifest = await safeReadJson(getManifestPath(cwd), { skills: [] });
+  if (!Array.isArray(manifest.skills)) manifest.skills = [];
+  return manifest;
+}
+
+export async function writeManifest(manifest, cwd = process.cwd()) {
+  await writeJson(getManifestPath(cwd), manifest);
+}
+
+export function upsertSkill(manifest, record) {
+  const idx = manifest.skills.findIndex((skill) => skill.name === record.name);
+  if (idx === -1) manifest.skills.push(record);
+  else manifest.skills[idx] = { ...manifest.skills[idx], ...record };
+}
+
+export function removeSkillFromManifest(manifest, skillName) {
+  manifest.skills = manifest.skills.filter((skill) => skill.name !== skillName);
+}

package/src/recommendations.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonIfExists(file) {
+  if (!(await exists(file))) return null;
+  return JSON.parse(await fs.readFile(file, 'utf8'));
+}
+
+async function readTextIfExists(file) {
+  if (!(await exists(file))) return '';
+  return fs.readFile(file, 'utf8');
+}
+
+/**
+ * Detecta tecnologías del proyecto. En modo hard hace una inspección más profunda.
+ */
+export async function detectProjectTechnologies(cwd = process.cwd(), { hard = false } = {}) {
+  const technologies = new Set();
+
+  const add = (...values) => values.filter(Boolean).forEach((value) => technologies.add(String(value).toLowerCase()));
+  const packageJson = await readJsonIfExists(path.join(cwd, 'package.json'));
+  if (packageJson) {
+    add('javascript', 'node', 'npm');
+    const deps = {
+      ...(packageJson.dependencies ?? {}),
+      ...(packageJson.devDependencies ?? {})
+    };
+    if (deps.react) add('react');
+    if (deps.vue) add('vue');
+    if (deps.svelte) add('svelte');
+    if (deps.next) add('nextjs', 'next');
+    if (deps.express || deps.fastify || deps.koa) add('api', 'backend');
+    if (deps.typescript) add('typescript', 'ts');
+    if (deps.tailwindcss) add('tailwind', 'css');
+  }
+
+  if (await exists(path.join(cwd, 'requirements.txt'))) add('python');
+  if (await exists(path.join(cwd, 'pyproject.toml'))) add('python');
+  if (await exists(path.join(cwd, 'go.mod'))) add('go', 'golang');
+  if (await exists(path.join(cwd, 'Cargo.toml'))) add('rust');
+  if (await exists(path.join(cwd, 'Dockerfile'))) add('docker', 'devops');
+  if (await exists(path.join(cwd, 'docker-compose.yml'))) add('docker', 'compose', 'devops');
+
+  if (hard) {
+    const readme = await readTextIfExists(path.join(cwd, 'README.md'));
+    const content = readme.toLowerCase();
+    if (content.includes('kubernetes') || content.includes('k8s')) add('kubernetes', 'k8s');
+    if (content.includes('postgres')) add('postgres', 'postgresql');
+    if (content.includes('mysql')) add('mysql');
+    if (content.includes('mongodb')) add('mongodb');
+  }
+
+  return Array.from(technologies);
+}