Guía de estilo

Convenciones y reglas de formato para contribuir a Claude How To. Siga esta guía para mantener el contenido consistente, profesional y fácil de mantener.

Índice

• Nombre de archivo y carpeta
• Estructura del documento
• Denominación
• Formato de texto
• Listas
• Cuadros
• Bloques de código
• Enlaces y referencias cruzadas
• Diagramas
• Uso de Emoji
• YAML Frontmatter
• Imágenes y medios de comunicación
• Tono y voz
• Enviar mensajes
• Lista de verificación para autores

Nombre de archivo y carpeta

Carpetas de lecciones

Las carpetas de lecciones usan un prefijo numerado de dos dígitos seguido de una kebab-case descriptor:

01-slash-commands/
02-memory/
03-skills/
04-subagents/
05-mcp/

El número refleja el orden de aprendizaje de la trayectoria de principiante a avanzado.

Nombres de archivo

Reglas

• Uso minúsculas para todos los nombres de archivos y carpetas (excepto documentos de nivel superior como README.md, CATALOG.md)
• Uso guiones (-) como separadores de palabras, nunca subraya o espacios
• Mantener los nombres descriptivos pero concisos

Estructura del documento

README de raíz

La raíz README.md sigue esta orden:

1. Logotipo (<picture> elemento con variantes oscuras/ligeras)
2. Título H1
3. Blockquote introductorio (propuesta de valor de una línea)
4. "¿Por qué esta guía?" sección con tabla de comparación
5. Regla horizontal (---)
6. Índice
7. Catálogo de funciones
8. Navegación rápida
9. Ruta de aprendizaje
10. Secciones de características
11. Primeros pasos
12. Mejores prácticas / Solución de problemas
13. Contribuyendo / Licencia

LECCIÓN

Cada lección README.md sigue esta orden:

1. Título H1 (por ejemplo, # Slash Commands)
2. Breve párrafo sinóptico
3. Tabla de referencia rápida (opcional)
4. Diagrama de arquitectura (Sirena)
5. Secciones detalladas (H2)
6. Ejemplos prácticos (número, 4 a 6 ejemplos)
7. Prácticas óptimas (tablas de hacer y no hacer)
8. Solución de problemas
9. Guías relacionadas / Documentación oficial
10. Pie de pie de metadatos del documento

Archivo de característica/ejemplo

Archivos de características individuales (por ejemplo, optimize.md, pr.md):

1. YAML frontmatter (si procede)
2. Título H1
3. Finalidad/descripción
4. Instrucciones de uso
5. Ejemplos de código
6. Consejos de personalización

Separadores de sección

Utilizar normas horizontales (---) para separar las principales regiones de documentos:

---

## New Major Section

Colocarlos después de la cita introductoria y entre partes lógicamente distintas del documento.

Denominación

Jerarquía

Reglas

• Un H1 por documento — el título de la página únicamente
• Nunca saltes los niveles — no saltar de H2 a H4
• Mantener los encabezados concisos — objetivo de 2-5 palabras
• Usar el caso de la oración — mayúsculas de la primera palabra y de los nombres propios únicamente (excepción: los nombres de las características permanecen como están)
• Añadir prefijos emoji sólo en la raíz README encabezados de sección (ver Uso de Emoji)

Formato de texto

Énfasis

Blockquotes para llamadas

Utilice blockquotes con prefijos en negrita para notas importantes:

> **Note**: Custom slash commands have been merged into skills since v2.0.

> **Important**: Never commit API keys or credentials.

> **Tip**: Combine memory with skills for maximum effectiveness.

Tipos de llamadas compatibles: Nota, Importante, Consejo, Aviso.

Párrafos

• Mantener los párrafos cortos (2-4 frases)
• Añadir una línea en blanco entre los párrafos
• Lidera con el punto clave, luego proporciona contexto
• Explicar el "por qué" no sólo el "qué"

Listas

Listas no ordenadas

Usar guiones (-) con hendidura de 2 espacios para anidar:

- First item
- Second item
  - Nested item
  - Another nested item
    - Deep nested (avoid going deeper than 3 levels)
- Third item

Listas ordenadas

Use listas numeradas para pasos secuenciales, instrucciones y elementos clasificados:

1. First step
2. Second step
   - Sub-point detail
   - Another sub-point
3. Third step

Listas descriptivos

Utilice etiquetas en negrita para listas de estilos de valor clave:

- **Performance bottlenecks** - identify O(n^2) operations, inefficient loops
- **Memory leaks** - find unreleased resources, circular references
- **Algorithm improvements** - suggest better algorithms or data structures

Reglas

• Mantener una sangría consistente (2 espacios por nivel)
• Añadir una línea en blanco antes y después de una lista
• Mantenga los elementos de la lista paralelos en la estructura (todos comienzan con verbo, o todos son sustantivos, etc.)
• Evite anidar más profundo que 3 niveles

Cuadros

Formato estándar

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |

Patrones de tabla comunes

Comparación de características (3-4 columnas):

| Feature | Invocation | Persistence | Best For |
|---------|-----------|------------|----------|
| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |
| **Memory** | Auto-loaded | Cross-session | Long-term learning |

Hacer y no hacer:

| Do | Don't |
|----|-------|
| Use descriptive names | Use vague names |
| Keep files focused | Overload a single file |

Referencia rápida:

| Aspect | Details |
|--------|---------|
| **Purpose** | Generate API documentation |
| **Scope** | Project-level |
| **Complexity** | Intermediate |

Reglas

• Encabezados de mesa de negrita cuando se trata de etiquetas de fila (primera columna)
• Alinear tuberías para la legibilidad en origen (opcional pero preferido)
• Mantenga el contenido de la celda conciso; use enlaces para obtener detalles
• Uso code formatting para comandos y rutas de archivo dentro de celdas

Bloques de código

Etiquetas del lenguaje

Especificar siempre una etiqueta de idioma para resaltar la sintaxis:

Convenios

# Comment explaining what the command does
claude mcp add notion --transport http https://mcp.notion.com/mcp

• Añadir una línea de comentarios antes de comandos no obvios
• Hacer todos los ejemplos listo para copiar-pegar
• Mostrar simple y avanzado versiones cuando proceda
• Incluir Producto previsto cuando ayuda a entender (utiliza un bloque de código sin etiquetar)

Bloques de instalación

Utilice este patrón para las instrucciones de instalación:

# Copy files to your project
cp 01-slash-commands/*.md .claude/commands/

Flujos de trabajo de varios pasos

# Step 1: Create the directory
mkdir -p .claude/commands

# Step 2: Copy the templates
cp 01-slash-commands/*.md .claude/commands/

# Step 3: Verify installation
ls .claude/commands/

Enlaces y referencias cruzadas

Enlaces internos (relativos)

Utilice rutas relativas para todos los enlaces internos:

[Slash Commands](01-slash-commands/)
[Skills Guide](03-skills/)
[Memory Architecture](02-memory/#memory-architecture)

De una carpeta de lecciones a raíz o hermano:

[Back to main guide](../README.md)
[Related: Skills](../03-skills/)

Enlaces externos (absolutos)

Utilice URLs completas con texto de anclaje descriptivo:

[Anthropic's official documentation](https://code.claude.com/docs/en/overview)

• Nunca utilice "clic aquí" o "este enlace" como texto ancla
• Usar texto descriptivo que tenga sentido fuera de contexto

Anclas de sección

Enlace a secciones dentro del mismo documento usando anclajes estilo GitHub:

[Feature Catalog](#-feature-catalog)
[Best Practices](#best-practices)

Patrón de guías relacionados

Fin de las lecciones con una sección de guías relacionadas:

## Related Guides

- [Slash Commands](../01-slash-commands/) - Quick shortcuts
- [Memory](../02-memory/) - Persistent context
- [Skills](../03-skills/) - Reusable capabilities

Diagramas

Mermaid

Use Sirena para todos los diagramas. Tipos compatibles:

• graph TB / graph LR — arquitectura, jerarquía, flujo
• sequenceDiagram — flujos de interacción
• timeline — secuencias cronológicas

GitHub renderiza Sirena de forma nativa. El sitio web y el EPUB renderizan la misma fuente con Pele, fijado en scripts/vendor_assets.py, y el mermaid-syntax pre-commit hook valida cada bloque con el mismo paquete, por lo que un bloque que pasa el hook renderiza por todas partes.

Convenciones de estilo

Aplicar colores consistentes usando bloques de estilo:

graph TB
    A["Componente A"] --> B["Componente B"]
    B --> C["Componente C"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#fce4ec,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333

paleta de colores:

Reglas

• Uso ["Label text"] para etiquetas de nodos (permite caracteres especiales)
• Uso <br/> para saltos de línea dentro de las etiquetas
• Mantenga las etiquetas de texto plano y escriba las etiquetas numeradas tal como están (["1. Load file"], no hay retrocesos antes del período)
• No confíes en %%{init}%% directivas o temas de Sirena: el sitio web aplica su propia paleta de luz y oscuridad
• Mantener diagramas simples (máximo 10-12 nodos)
• Añádase una breve descripción de texto debajo del diagrama de accesibilidad
• Usar de arriba a abajo (TB) para las jerarquías, de izquierda a derecha (LR) para flujos de trabajo

Uso de Emoji

Donde se usan los emojis

Se utilizan emojis con moderación y propósito — sólo en contextos específicos:

Conjunto estándar de emojis

Reglas

• Nunca use emojis en el texto corporal o párrafos
• Sólo use emojis en las cabeceras en la raíz README (no en la lección READMEs)
• No añadir emojis decorativos — cada emoji debe transmitir significado
• Mantener el uso de emojis consistente con la tabla de arriba

YAML Frontmatter

Archivos de características (skills, órdenes, agentes)

---
name: unique-identifier
description: What this feature does and when to use it
allowed-tools: Bash, Read, Grep
---

Campos opcionales

---
name: my-feature
description: Brief description
argument-hint: "[file-path] [options]"
allowed-tools: Bash, Read, Grep, Write, Edit
model: opus                        # opus, sonnet, or haiku
disable-model-invocation: true     # User-only invocation
user-invocable: false              # Hidden from user menu
context: fork                      # Run in isolated subagent
agent: Explore                     # Agent type for context: fork
---

Reglas

• Coloque frontmatter en la parte superior del archivo
• Uso kebab-case para la name campo
• Mantener description a una oración
• Sólo incluyen los campos que se necesitan

Imágenes y medios de comunicación

Patrón del logotipo

Todos los documentos que comienzan con un logotipo utilizan el <picture> elemento para el soporte de modo oscuro/luz:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
  <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
</picture>

Imágenes de pantalla

• Almacenar en la carpeta de lecciones pertinente (por ejemplo, 01-slash-commands/pr-slash-command.png)
• Usar nombres de archivos de kebab-case
• Incluir texto descriptivo alt
• Prefiere SVG para diagramas, PNG para capturas de pantalla

Reglas

• Proporcionar siempre texto alt para las imágenes
• Mantener los tamaños de archivo de imagen razonables (< 500KB para PNGs)
• Usar rutas relativas para referencias de imágenes
• Almacenar imágenes en el mismo directorio que el documento que las hace referencia, o en assets/ para imágenes compartidas

Tono y voz

Estilo de escritura

• Profesional, pero accesible — precisión técnica sin sobrecarga de jerga
• Voz activa - "Crear un archivo" no "Debe crearse un archivo"
• Instrucciones directas - "Ejecutar esta orden" no "Es posible que desee ejecutar esta orden"
• Amigo de los principiantes — asumir que el lector es nuevo en Claude Code, no nuevo en la programación

Principios de contenido

Vocabulario

• Usar "Claude Code" (no "CLI de Claude" o "la herramienta")
• Use "skill" (no "comando personalizado" — término heredado)
• Usar "lección" o "guía" para las secciones numeradas
• Usar "ejemplo" para archivos de características individuales

Enviar mensajes

Seguir Comisiones convencionales:

type(scope): description

Tipos

Ámbitos de aplicación

Utilice el nombre de la lección o el área de archivo como ámbito:

feat(slash-commands): Add API documentation generator
docs(memory): Improve personal preferences example
fix(README): Correct table of contents link
docs(skills): Add comprehensive code review skill

Metadatos de documentos

LECCIÓN READMEs terminan con un bloque de metadatos:

---
**Last Updated**: August 25, 2026
**Claude Code Version**: 2.1.245
**Compatible Models**: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5

• Utilice la versión capturada por la ejecución de sincronización actual, no el valor mostrado aquí
• Usar formato mes + día + año (por ejemplo, "20 de mayo de 2026")
• Actualizar la versión cuando las características cambian
• Listar todos los modelos compatibles

Lista de verificación para autores

Antes de enviar el contenido, verifique:

• [ ] Nombres de archivos/carpetas usan kebab-case
• [ ] El documento comienza con el título H1 (uno por archivo)
• [ ] Jerarquía de encabezados es correcta (no se saltan los niveles)
• [ ] Todos los bloques de código tienen etiquetas de idioma
• [ ] Los ejemplos de código están listos para copiar y pegar
• [ ] Los enlaces internos utilizan rutas relativas
• [ ] Enlaces externos tienen texto de anclaje descriptivo
• [ ] Las tablas están correctamente formateadas
• [ ] Los emojis siguen el conjunto estándar (si se utilizan en absoluto)
• [ ] Los diagramas Mermaid utilizan la paleta de colores estándar
• [ ] No hay información sensible (claves de la API, credenciales)
• [ ] La materia frontal de YAML es válida (si procede)
• [ ] Las imágenes tienen texto alt
• [ ] Los párrafos son breves y están centrados
• [ ] Enlaces de la sección de guías relacionadas con las lecciones pertinentes
• [ ] Mensaje de comisión sigue el formato de confirmación convencional

Última actualización: 25 de agosto de 2026 Versión de Claude Code: 2.1.245 Fuenteshttps://code.claude.com/docs/en/overview - https://code.claude.com/docs/en/changelog - https://code.claude.com/docs/en/model-config - https://github.com/anthropics/claude-code/releases/tag/v2.1.154 Modelos compatibles: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5