📁 Las dos carpetas
¿Eres nuevo aquí? Una skill está en una carpeta con su nombre, que contiene el
`skill.md`. Esa carpeta puede estar en dos lugares: dentro de .claude/skills/
DENTRO de un proyecto específico —solo existe para quien abra ese proyecto— o dentro de
~/.claude/skills/, la carpeta personal del usuario (`~` significa «tu carpeta
de usuario», igual que Documentos o Descargas), disponible en CUALQUIER proyecto que abras después.
Piénsalo así: la carpeta del proyecto es el cajón del escritorio de esa oficina en particular — solo quienes trabajan ahí ven lo que hay dentro. La carpeta personal es la mochila que llevas a todas partes — lo que está ahí, va contigo a cualquier oficina a la que entres.
Leyenda: a la izquierda, la skill del proyecto solo ilumina el proyecto donde reside (los demás quedan apagados). A la derecha, la skill global ilumina todos los proyectos por igual: te acompaña dondequiera que abras el agente.
🏢 Cuándo usar una skill de proyecto
Skill de proyecto sirve para un proceso específico DE ESE cliente o repositorio — algo que no tiene sentido fuera de ahí. Ejemplo: «cómo generar el informe mensual DE ESTE cliente» (con el formato de la hoja de cálculo, el diseño del PDF y sus reglas de negocio exclusivas). Si abres otro proyecto, esta skill ni siquiera aparece — y está bien que sea así, porque ahí no serviría de nada.
🔍 Por dentro
- Portabilidad: la skill viaja JUNTO con el `git` del proyecto: quien clona el repo también obtiene la skill.
- Especificidad permitida: puedes mencionar nombres de archivo, formato exacto y una regla de negocio específica — sin miedo a «romper» algo en otro lugar, porque no irá a otro lugar.
🌍 Cuándo usar una skill global
Una skill global sirve para un proceso que se repite en CUALQUIER contexto tuyo, sin importar en qué proyecto estés. Ejemplo real de este mismo curso: la skill «formato-curso-v2», usada para armar toda esta ruta, es global: sirve para cualquier curso INEMA, no solo para wat7d. Otro ejemplo: «cómo escribir un correo con mi tono de voz»: tu tono de voz no cambia de un proyecto a otro, así que la skill no debería quedar ligada a ninguno.
✨ Consejo práctico
Regla práctica: si puedes imaginar usando esta misma skill en un proyecto totalmente diferente del actual, sin cambiar nada, puede ser global. Si alguna frase de la skill menciona algo exclusivo de este proyecto, es específica del proyecto.
⚖️ Mantenimiento y portabilidad: el equilibrio
La elección implica tres trade-offs reales. Mantenimiento: la skill global debe ser lo bastante genérica como para servir en varios lugares; si la haces demasiado específica (mencionando un archivo o una regla de un solo proyecto), FALLA cuando se usa en otro. Portabilidad: la skill del proyecto viaja con el `git` de ese proyecto (quien lo clona la obtiene); la skill global se queda solo en tu máquina, a menos que la copies manualmente a otro lugar. Organización: la carpeta global crece con el tiempo y se convierte en tu "caja de herramientas personal" — encontrarás más información sobre esto en el tema 5.
✓ Elección correcta
- ✓Skill «generar guía de proyecto» (global) — se usa en cada proyecto que creas.
- ✓Skill «publicar release de esta app» (proyecto) — cita el pipeline exacto de ese repo.
✗ Elección equivocada
- ✗Skill global que menciona «el archivo `vendas_2026.xlsx` de este cliente»: falla en otro proyecto.
- ✗Skill de proyecto para tu tono de correo personal: desaparece cuando cambias de repositorio.
🧰 La caja de herramientas personal
Con el tiempo, tu carpeta ~/.claude/skills/ vas acumulando skills globales:
una para generar una guía de proyecto, otra para el tono de los correos, otra para revisar código y otra para crear videos.
Es lo esperado y es bueno: estás construyendo una caja de herramientas que abarca todos tus
proyectos. Aquí hay que tener el mismo cuidado que en el módulo 3.4: las descriptions bien diferenciadas evitan que la caja de
herramientas se convierta en un desorden de skills que compiten entre sí.
Las dos rutas de carpetas, una al lado de la otra
# Skill de PROJETO — só existe abrindo esta pasta
meu-projeto-cliente-x/
.claude/
skills/
relatorio-mensal-cliente-x/
skill.md
# Skill GLOBAL — disponível em qualquer projeto
~/.claude/
skills/
formato-curso-v2/
skill.md
references/
tom-de-email-pessoal/
skill.md🌳 La pregunta que decide
Toda la decisión de este módulo se resume en una pregunta, siempre la misma, antes de crear una skill nueva: «¿este proceso es solo de este proyecto o sirve para cualquiera que abra?» La respuesta te lleva directamente a la carpeta correcta, sin adivinar.
Pregunta: "¿Este proceso menciona algún archivo, cliente o regla de negocio ÚNICOS de este proyecto?"
→ .claude/skills/ — skill del proyecto.
→ ~/.claude/skills/ — skill global, se agrega a tu caja de herramientas.
Ejercicio — clasifica estos 3 ejemplos
- "Generar la factura en el formato exacto que acepta el sistema del Cliente Y."
- "Revisa cualquier texto mío para detectar errores de portugués antes de publicarlo."
- "Ejecuta el script de deploy específico de este repositorio, con las variables de entorno de aquí."
Respuesta esperada: 1 y 3 son de proyecto (mencionan un sistema o repo específico); 2 es global (sirve para cualquier texto tuyo, en cualquier proyecto).
✨ Consejo práctico
Si dudas, empieza con una skill de proyecto: después es más fácil convertirla en una skill global (solo tienes que generalizar el texto y mover la carpeta) que descubrir tarde que una skill «global» solo funcionaba por accidente en un único proyecto.
Verificación rápida (opcional): ¿qué pregunta decide si una skill debe ser de proyecto o global?