Output Styles para Claude Code, un tono propio en 20 minutos

Conoces el problema. Claude Code responde súper útil, pero a veces demasiado largo, a veces demasiado casual, a veces con pseudo-optimismo que ahora mismo no necesitas. Estás en modo code review y quieres crítica dura, no "this looks great overall". Para eso están los Output Styles. Un archivo Markdown, un snippet de prompt, y Claude Code adopta otra personalidad para la sesión o para toda la codebase.

1. Entender qué son los Output Styles en realidad

Un Output Style es un archivo Markdown con frontmatter YAML que Claude Code carga como fragmento adicional del system prompt. A diferencia de las skills o sub-agentes, un Output Style no cambia las herramientas que Claude usa, solo cómo comunica. Tono, severidad, nivel de detalle, idioma, formato.

Eso significa que un Output Style es bueno para "quiero que Claude responda escueto" o "necesito lenguaje sobrio de code review". Es malo cuando lo que realmente quieres es cambiar herramientas, entonces necesitas una skill o sub-agente.

2. Crear el directorio

Hay dos sitios: a nivel de usuario en ~/.claude/output-styles/ y a nivel de proyecto en .claude/output-styles/. El nivel usuario aplica a todos los proyectos, el nivel proyecto sobrescribe al de usuario cuando un nombre aparece dos veces. Los plugins también pueden traer Output Styles, pero eso es otro tema.

Para el primer test basta el directorio de usuario:

mkdir -p ~/.claude/output-styles

3. Escribir el primer style

Crea un archivo direct.md. Frontmatter con name y description, el body es el prompt que se cuelga al system prompt.

---
name: Direct Reviewer
description: Code reviews escuetos y honestos sin diplomacia
---

Respondes escueto y sobrio. Sin floritura tipo "great work" o
"looks good overall". Cuando el código tiene problemas, lo dices directo en la primera frase.

En code reviews:
- Primero los problemas críticos, luego los menores
- Propuestas concretas con número de línea
- Sin himnos resumen de elogios al final
- Si el código está bien, una frase basta

Guardar, listo. La próxima vez que arranques Claude Code, el style está disponible.

4. Activar el style

Dentro de Claude Code escribes /output-style y recibes la lista de todos los styles disponibles. Default siempre está, más los que te hayas creado. Eliges, listo. La selección aplica a la sesión activa.

Si quieres el style como default a nivel de proyecto, puedes fijarlo en el settings.json del proyecto. Yo lo uso para codebases donde todo el equipo debería ver el mismo tono.

5. Use cases concretos que valen la pena

Tengo cuatro styles en uso diario. Primero "direct" para code reviews y debugging, ahí no quiero diplomacia. Segundo "tutor" cuando me hago explicar algo, el style le dice a Claude que pregunte por suposiciones en vez de adivinar. Tercero "german-only" que fuerza alemán en la respuesta porque Claude si no se va al inglés tras 5 frases. Cuarto "diff-only" que en cambios de código devuelve solo el unified diff, sin prosa alrededor.

En "diff-only" me di cuenta de que Claude no se atiene al 100 por cien, a veces sigue colándose una frase de explicación. Eso es un problema de prompt adherence, no un bug de Output Styles. En constraints importantes mejor formular doble ("solo diff, sin explicación adicional, sin texto antes ni después del bloque diff").

6. Style vs. CLAUDE.md vs. skill, qué se diferencia

Esa fue mi primera confusión. Tres mecanismos que influyen en el comportamiento de Claude. Aquí va el corte corto como yo lo uso.

CLAUDE.md lo dejas para conocimiento específico del proyecto, "la DB se llama X, la ENV var es Y, el script de deploy se llama Z". Output Style es para personalidad y formato. Skill es para un workflow recurrente con herramientas, por ejemplo "comprueba el cookie banner con tres pasos específicos".

Si no estás seguro de qué necesitas: cambiar tonalidad es style, transmitir conocimiento es CLAUDE.md, secuencia de pasos con herramientas es skill.

7. La trampa con el orden

Output Style se cuelga al system prompt, después de CLAUDE.md. Eso significa que lo que está en el style suele pesar más que lo que está en el CLAUDE.md. Cuando los dos se contradicen, suele ganar el style.

En mi caso pasó: CLAUDE.md decía "responde siempre con ejemplos de código cuando sea posible", el style "direct" decía "mantenlo lo más corto posible". Resultado: cero ejemplos de código. Tuve que ajustar el style, porque la regla del proyecto era más importante.

Lección: en conflictos, mejor suavizar el style que inflar el CLAUDE.md. Style es capa de sesión, CLAUDE.md es capa de proyecto.

8. Team setup con styles de proyecto

Cuando trabajas en equipo, los styles importantes van en el repo bajo .claude/output-styles/. Eso lo comiteas, todos lo tienen. Ejemplo: un style "release-notes" que fija el tono para entradas de changelog, un style "incident-postmortem" para reports de outage.

Importante aquí: nada de secretos en los Output Styles. Acaban en Git, todos los ven. Sin claves API, sin rutas internas, sin nombres de cliente que no deban ser públicos. Los Output Styles son artefactos de doc con efecto de system prompt, trátalos como archivos README.

9. Debuggear cuando el style no engancha

Tres cosas que me pasaron. Primera, style creado, Claude Code ya corría, el style nuevo no se mostraba. Solución: reiniciar Claude Code o invocar /output-style una vez, a veces eso dispara un reload. Segunda, el style aparece pero no está activo, simplemente no lo había elegido. /output-style muestra el style activo actual con marca. Tercera, el style está activo pero Claude no lo sigue. Ahí solo ayuda formular el prompt del style más claro y más imperativo. "Responde escueto" funciona peor que "Máximo tres frases por respuesta, sin florituras introductorias".

10. Qué viene después

Cuando los Output Styles te hayan hecho clic, mira Skills para Claude Code, porque entonces tienes encima la siguiente capa: workflows que no solo fijan tono, también secuencias de herramientas. O lee Tus propios slash commands para Claude Code si quieres combinar el style por llamada con comandos concretos.

Para la capa de lessons encaja Hooks y Skills como refresher de concepto, eso afila el límite de cuándo usar qué.

Source

Output Styles oficial: https://code.claude.com/docs/en/output-styles