📁 .claude/skills/ del proyecto
El directorio .claude/skills/ queda en la raíz de tu repositorio. Las Skills allí tienen alcance local: existen solo para quienes trabajan en ese proyecto específico.
El directorio .claude/skills/ en la raíz del repositorio está el espacio de skills con alcance de proyecto. Cualquier skill que coloques allí estará disponible solo cuando Claude Code se esté ejecutando dentro de ese repo.
Cada skill es una subcarpeta. El nombre de la carpeta es exactamente el nombre con el que Claude la reconoce, por ejemplo: .claude/skills/video-explicativo/.
- ✓ La skill es específica para ese producto o cliente
- ✓ Quieres versionar la skill junto con el código
- ✓ Todo el equipo debe usar la misma versión de la skill
- ✓ La skill cambia con cada sprint junto con el proyecto
- ✗ La skill sirve para todos tus proyectos personales
- ✗ El repo es público y la skill contiene datos sensibles
- ✗ Estás probando un borrador temporal
- ✗ La skill debe funcionar fuera de cualquier proyecto
🌐 ~/.claude/skills/ global
El directorio global está en ~/.claude/skills/ (directorio personal del usuario). Las Skills de allí se aplican absolutamente a cualquier proyecto que abras en la máquina.
- • Dentro del repositorio
- • Versionado en git
- • Compartido con el equipo mediante clone
- • Alcance: solo este proyecto
- • En la página de inicio del usuario
- • Fuera de cualquier repo
- • Solo en tu máquina (no se clona)
- • Alcance: todos los proyectos
Si existe una skill con el mismo nombre en ambos lugares (local y global), la versión local (.claude/skills/) tiene prioridad. Aprovecha esto: coloca en el proyecto una versión personalizada de una skill que normalmente usas de forma global.
📋 Instalar copiando la carpeta
La forma más sencilla de instalar una skill es copiar la carpeta o descomprimir un .zip — en el directorio correcto. Así es exactamente como recibiste la skill video-explicativo de este curso.
La skill puede venir como una carpeta comprimida (video-explicativo.zip), un repositorio separado o simplemente una carpeta que alguien del equipo te envió. El contenido mínimo siempre es: SKILL.md en la raíz de la carpeta.
Si recibiste un zip: unzip video-explicativo.zip. El resultado debe ser una carpeta con el nombre de la skill como raíz: confírmalo antes de moverla.
Para el alcance local: mv video-explicativo/ .claude/skills/. Para el alcance global: mv video-explicativo/ ~/.claude/skills/. Crea el directorio si no existe: mkdir -p .claude/skills/.
Abre Claude Code en la sesión del proyecto. La skill ya estará disponible; solo tienes que invocarla con el nombre configurado en SKILL.md. No hace falta reiniciar ni recargar.
No hay binarios, no hay build, no hay dependencias npm que instalar. Una skill son 100 % archivos de texto: markdown, scripts shell, templates. Copiar la carpeta ES la instalación completa.
⌨️ Por comando
Además de copiar manualmente, puedes instalar skills mediante CLI, como npx skills add — que accede a un catálogo centralizado y descarga automáticamente.
Herramientas como npx skills add <nome> abstraen el proceso de copiar manualmente: buscan el paquete en el catálogo, lo descargan y lo colocan automáticamente en el lugar correcto.
Es el mismo patrón de npm install pero para skills de Claude Code: sin package.json, sin node_modules, solo la carpeta de la skill.
- ✓ Skills públicas del catálogo oficial
- ✓ Quieres garantizar la versión más reciente
- ✓ El equipo nuevo necesita configurar el entorno rápidamente
- ✓ Quieres explorar el catálogo de skills disponibles
- ✗ Skills internas/privadas de la empresa (no publicadas)
- ✗ Necesitas una versión personalizada específica
- ✗ Entorno sin acceso a Internet
- ✗ La skill todavía está en desarrollo local
🔁 Versionar en git
Una skill es texto plano — por lo tanto, encaja naturalmente en git. Esto significa historial, diff, revisión de PR, rollback y trazabilidad completa de quién cambió qué en la skill.
Cuando la skill y el código evolucionan juntos en el mismo commit, siempre sabes exactamente qué versión de la skill produjo cada output. Nunca más «la skill cambió y el video quedó diferente» sin seguimiento.
Skills en ~/.claude/skills/ quedan fuera de cualquier repositorio y NO se versionan automáticamente. Si quieres una copia de seguridad o un historial de tu skill global, crea un repositorio dedicado (p. ej.: meus-skills-pessoais/) y sincroniza manualmente.
Escribe SKILL.md + referencias → git add + commit
Corrige el prompt, agrega una referencia → nuevo commit — diff visible en el PR
El equipo revisa los cambios en la skill igual que revisa el código: comentarios línea por línea
git tag v1.2-skill — congela el skill en un estado estable para producción
🤝 Compartir con el equipo
Skill en el repositorio significa que cada desarrollador que clone el proyecto recibe automáticamente las mismas skills — sin instalación manual ni diferencias entre máquinas.
Cuando la skill vive en .claude/skills/ en el repositorio, cualquier git clone incluye el entorno completo. ¿Hay un nuevo desarrollador en el equipo? Clona y ya tiene la skill. ¿Una máquina nueva? Clona y ya funciona.
Esto elimina la pregunta "¿qué versión del skill estás usando?" — todos usan exactamente lo que está en el commit actual del repo.
- ✓ Documenta la skill en el README: qué es y cómo invocarla
- ✓ Incluye ejemplos reales de uso en SKILL.md
- ✓ Usa PR para cualquier cambio en la skill (revisión)
- ✓ Mantén las referencias actualizadas cuando cambie el proyecto
- ✗ Hacer commit de claves de API o tokens dentro de la skill
- ✗ Skill con rutas absolutas que solo existen en tu máquina
- ✗ Modificar la skill sin comunicar los cambios al equipo
- ✗ Skill que depende de software no incluido en los requisitos previos
git clone <repo>ls .claude/skills/El SKILL.md de la skill no contiene solo instrucciones para Claude: es documentación real de lo que usa el equipo y cómo lo usa. Mantenlo tan actualizado como mantendrías un README de una función crítica.
📚 Resumen del Módulo 1.4
Completaste la Ruta 1 — Skills. Esto es todo lo que dominas:
.claude/skills/ del proyecto — alcance limitado al repositorio
~/.claude/skills/ — disponibles en cualquier proyecto de la máquina
npx skills add automatizan la descarga del catálogo
Ruta 2 — Pipeline. Descubre el framework de código abierto que transforma HTML animado en MP4 local, sin nube ni costo por render, y cómo se conecta con todo lo que aprendiste sobre skills en la Ruta 1.