Mejores Prácticas Para Skills Con Claude

Cuándo conviene instalar un skill a nivel global y cuándo dejarlo dentro de un proyecto específico. Diferencias claras entre skills, herramientas y plugins.

La confusión que más se repite en la comunidad: cuándo poner una skill global vs. por proyecto, y cuál es la diferencia real entre skills, herramientas y plugins. Esta nota cierra esa duda con regla clara, ejemplos concretos, y un decision tree de 6 preguntas.

La diferencia entre skills, herramientas y plugins (de una)

Conviene fijar terminología porque la gente mezcla los tres:

Skills

Qué son: archivos .md con instrucciones que Claude lee cuando aplican. Texto, no código.

Vivienda: carpetas en ~/.claude/skills/ (global) o <repo>/.claude/skills/ (proyecto).

Cuándo se cargan: cuando Claude detecta que la descripción de la skill matchea el pedido del usuario.

Ejemplo: una skill "humanízalo" que detecta texto AI-sounding y reescribe.

Herramientas (tools / MCPs)

Qué son: funciones externas que Claude llama. Tienen API, schema, hacen algo concreto fuera del contexto del chat.

Vivienda: servidores MCP (locales o remotos) configurados en Claude.

Cuándo se invocan: cuando Claude decide llamar la función como parte de su razonamiento.

Ejemplo: Gmail MCP que permite a Claude leer/enviar mails.

Plugins

Qué son: combinación de skills + tools, distribuidos como paquete único. A veces incluyen scripts ejecutables, configuración de hooks, recursos extra.

Vivienda: se instalan con npx skills@latest add y se desempaquetan en las ubicaciones apropiadas.

Cuándo aplican: cuando la skill que el plugin trae se activa.

Ejemplo: "Claude Code Plugin Pack X" que trae 3 skills + 2 MCPs + 5 templates.

La regla mnemotécnica

Skills: conocimiento (cómo hacer cosas).
Tools/MCPs: acceso (qué puedo invocar).
Plugins: paquetes combinados (skills + tools + recursos).

Cuando alguien dice "una skill que llama a Gmail", técnicamente es un plugin (skill + tool). Pero la gente lo dice así informalmente.

Skills globales vs. por proyecto: la regla

La regla simple:

Global cuando aplica a vos en cualquier contexto. Por proyecto cuando aplica al proyecto específico.

Pero la regla simple no alcanza. Más concreto:

Va en global (`~/.claude/skills/`) si:

La usás en >2 proyectos.
Es sobre cómo trabajás vos (estilo, tono, preferencias).
No depende de tech stack específico.
No tiene credentials específicas de un cliente/empresa.

Ejemplos:

humanízalo — sirve en todos los proyectos donde escribís.
commit-style — define cómo querés que sean los commits, sirve en todo repo tuyo.
review — tu estilo de code review, transversal.

Va por proyecto (`<repo>/.claude/skills/`) si:

Solo aplica a este repo.
Depende del tech stack del repo.
Tiene knowledge específico del negocio.
Tiene credentials del proyecto.

Ejemplos:

deploy-staging — sabe cómo se deployan tus servicios en infra Y.
migrate-db — usa tu CLI custom de migraciones.
release-notes — formato específico de tu CHANGELOG.

Decision tree de 6 preguntas

Si dudás dónde poner una skill nueva:

1. ¿La usaría en otro proyecto si lo tuviera?

Sí → continúa al 2.
No → proyecto.

2. ¿Depende de configuración específica de un repo?

Sí → proyecto.
No → continúa al 3.

3. ¿Tiene credentials o secrets de un cliente?

Sí → proyecto.
No → continúa al 4.

4. ¿Es sobre tu estilo personal de trabajar?

Sí → global.
No → continúa al 5.

5. ¿Es de un cliente o de vos?

Mío → global.
Cliente → proyecto.

6. ¿Para más de 3 proyectos similares?

Sí → global.
No → proyecto.

Al final, una de las dos. Si todavía dudás: empezala en proyecto, y si la copiás a un segundo proyecto, ahí movela a global.

Caso: skills que evolucionan

Patrón común: arrancás una skill como "proyecto-específica" pero notás que está usándola en 3 proyectos. Tiempo de mudarla a global.

Pasos:

Movés el archivo:

cp <repo>/.claude/skills/mi-skill/SKILL.md ~/.claude/skills/mi-skill/SKILL.md

Removés referencias específicas del proyecto:

Cambia usa nuestro CLI custom por usa el CLI configurado en el proyecto.
Quita paths absolutos.
Generaliza nombres de archivos.

Borrás de los proyectos:

rm -r <repo>/.claude/skills/mi-skill/

Si la skill global tiene un trigger específico a un proyecto, ese trigger va en el CLAUDE.md del repo, no en la skill.

Anti-patrones comunes

Anti-patrón 1: poner todo en global

Resultado: tu Claude global tiene 50 skills cargadas. Muchas no aplican a la tarea actual pero se cargan parcialmente y confunden. Performance baja.

Solución: auditar skills globales cada 2-3 meses. Las que no usás, desinstalá. Las que usás solo en un proyecto, movelas allá.

Anti-patrón 2: duplicar skills

Tenés una skill global "review" y otra <repo>/.claude/skills/review. Cuando Claude busca cuál cargar, puede haber conflicto.

Regla: un nombre, una ubicación. Si el local quiere modificar al global, mejor que extienda con instrucciones en CLAUDE.md del repo, no creando skill duplicada.

Anti-patrón 3: skills con credentials hardcoded

Nunca poner API keys, tokens, passwords en una skill. Las skills son texto plano y se versionan. Si la skill se publica, te queman las credentials.

Solución: las credentials van en env vars o secret managers. La skill se refiere a ellas con nombres de variables (STRIPE_SECRET_KEY), no con valores.

Anti-patrón 4: skills muy específicas con instrucciones globales

Una skill humanizalo-para-cliente-X con instrucciones específicas del cliente X en global confunde a Claude en otros proyectos.

Solución: si la personalización es por cliente, va en el proyecto del cliente. Global sólo lo realmente universal.

Anti-patrón 5: SKILL.md gigante

Una skill con SKILL.md de 8.000 palabras gasta tokens cada vez que se carga. Aún cuando solo necesitabas el 5%.

Solución: progressive disclosure. SKILL.md corto con principios; archivos en references/ con detalles cargados bajo demanda.

Cómo organizar tu carpeta global

Después de varios meses, ~/.claude/skills/ puede tener 30+ skills. Convención que rinde:

~/.claude/skills/
  ├── code/
  │   ├── review/
  │   ├── refactor/
  │   ├── tests/
  ├── writing/
  │   ├── humanizalo/
  │   ├── copywriter/
  │   ├── newsletter/
  ├── research/
  │   ├── deep-research/
  │   ├── comparativa/
  ├── workflow/
  │   ├── plan-mode-enforce/
  │   ├── commit-semantic/

Carpetas por categoría te ayuda a:

Encontrar rápido cuando querés modificar.
Hacer revisión periódica organizada.
Compartir un subset (zipear ~/.claude/skills/code/ para mandar a un compañero).

Cómo organizar las del proyecto

Por proyecto, mantener <repo>/.claude/skills/ lo más chico posible:

.claude/
  ├── skills/
  │   ├── deploy-staging/
  │   ├── migrate-db/
  │   ├── release-notes/
  ├── settings.json  # config del proyecto

Idealmente 3-7 skills por proyecto. Más significa que algunas deberían ser globales.

CLAUDE.md como capa de orquestación

Las skills se activan automático según description. Pero a veces querés forzar uso. El CLAUDE.md del proyecto es donde lo hacés:

## Skills mandatorias en este proyecto

Para cualquier tarea que toque deploy, usá la skill /deploy-staging.

Para tareas de DB, usá /migrate-db (no escribir migrations a mano).

Antes de cada commit, corré /code-review.

Eso refuerza el uso de skills clave sin depender de que Claude las detecte autónomamente.

Skills en equipo: la complicación

Si trabajás en equipo, todos tienen sus skills globales (personales) y todos comparten las skills del proyecto. Reglas para mantener cordura:

Skills globales personales: cada uno las suyas, no se comparten.
Skills del proyecto: versionadas en git (.claude/skills/ debe estar comiteado).
PRs sobre skills: una skill que cambia comportamiento del proyecto se review como código.
Documentación: cada skill del proyecto debe tener README con qué hace y cómo se invoca.

Sin estas reglas, la skill que escribió uno rompe el flow del otro.

Conclusión

La regla de "global para mí, proyecto para el repo" es simple pero requiere disciplina aplicarla. Los anti-patrones (todo en global, duplicar, credentials hardcoded, skills gigantes) son los que rompen la productividad a largo plazo.

Si recién arrancás con skills, pegate a la regla. Si ya tenés meses de uso, hacé auditoría: listá globales, decidí cuáles bajar a proyecto, cuáles desinstalar. Tu Claude va a sentirse más rápido y consistente.

Tags: skills, global, proyecto, claude-code, habilidades, plugins, agentes, organizacion