everything-claude-code/docs/es/CONTRIBUTING.md

# Contribuir a Everything Claude Code

¡Gracias por querer contribuir! Este repositorio es un recurso comunitario para usuarios de Claude Code.

## Tabla de Contenidos

- [Qué Buscamos](#qué-buscamos)
- [Inicio Rápido](#inicio-rápido)
- [Contribuir Skills](#contribuir-skills)
- [Política de Adaptación de Skills](#política-de-adaptación-de-skills)
- [Contribuir Agentes](#contribuir-agentes)
- [Contribuir Hooks](#contribuir-hooks)
- [Contribuir Comandos](#contribuir-comandos)
- [MCP y Documentación (por ejemplo, Context7)](#mcp-y-documentación-por-ejemplo-context7)
- [Cross-Harness y Traducciones](#cross-harness-y-traducciones)
- [Proceso de Pull Request](#proceso-de-pull-request)

---

## Qué Buscamos

### Agentes
Nuevos agentes que manejen tareas específicas de forma eficiente:
- Revisores específicos de lenguaje (Python, Go, Rust)
- Expertos en frameworks (Django, Rails, Laravel, Spring)
- Especialistas en DevOps (Kubernetes, Terraform, CI/CD)
- Expertos de dominio (pipelines de ML, ingeniería de datos, móvil)

### Skills
Definiciones de flujos de trabajo y conocimiento de dominio:
- Mejores prácticas por lenguaje
- Patrones de frameworks
- Estrategias de prueba
- Guías de arquitectura

### Hooks
Automatizaciones útiles:
- Hooks de linting/formateo
- Verificaciones de seguridad
- Hooks de validación
- Hooks de notificación

### Comandos
Comandos slash que invocan flujos de trabajo útiles:
- Comandos de despliegue
- Comandos de prueba
- Comandos de generación de código

---

## Inicio Rápido

```bash
# 1. Hacer fork y clonar
gh repo fork affaan-m/everything-claude-code --clone
cd everything-claude-code

# 2. Crear una rama
git checkout -b feat/mi-contribucion

# 3. Añadir tu contribución (ver secciones abajo)

# 4. Probar localmente
cp -r skills/mi-skill ~/.claude/skills/  # para skills
# Luego probar con Claude Code

# 5. Enviar PR
git add . && git commit -m "feat: add mi-skill" && git push -u origin feat/mi-contribucion
```

---

## Contribuir Skills

Las skills son módulos de conocimiento que Claude Code carga según el contexto.

> **Guía Completa:** Para orientación detallada sobre cómo crear skills efectivas, consulta la [Guía de Desarrollo de Skills](../SKILL-DEVELOPMENT-GUIDE.md). Cubre:
> - Arquitectura y categorías de skills
> - Escribir contenido efectivo con ejemplos
> - Mejores prácticas y patrones comunes
> - Prueba y validación
> - Galería de ejemplos completos

### Estructura de Directorios

```
skills/
└── nombre-de-tu-skill/
    └── SKILL.md
```

### Plantilla de SKILL.md

```markdown
---
name: nombre-de-tu-skill
description: Descripción breve mostrada en la lista de skills y usada para activación automática
origin: ECC
---

# Título de Tu Skill

Resumen breve de lo que cubre esta skill.

## Cuándo Activar

Describe los escenarios donde Claude debería usar esta skill. Esto es fundamental para la activación automática.

## Conceptos Clave

Explica patrones y directrices principales.

## Ejemplos de Código

\`\`\`typescript
// Incluye ejemplos prácticos y probados
function ejemplo() {
  // Código bien comentado
}
\`\`\`

## Anti-Patrones

Muestra lo que NO se debe hacer con ejemplos.

## Mejores Prácticas

- Directrices accionables
- Qué hacer y qué no hacer
- Errores comunes que evitar

## Skills Relacionadas

Enlaza a skills complementarias (por ejemplo, `skill-relacionada-1`, `skill-relacionada-2`).
```

### Categorías de Skills

| Categoría | Propósito | Ejemplos |
|-----------|---------|----------|
| **Estándares de Lenguaje** | Modismos, convenciones, mejores prácticas | `python-patterns`, `golang-patterns` |
| **Patrones de Framework** | Orientación específica del framework | `django-patterns`, `nextjs-patterns` |
| **Flujo de Trabajo** | Procesos paso a paso | `tdd-workflow`, `refactoring-workflow` |
| **Conocimiento de Dominio** | Dominios especializados | `security-review`, `api-design` |
| **Integración de Herramientas** | Uso de herramientas/bibliotecas | `docker-patterns`, `supabase-patterns` |
| **Plantilla** | Plantillas de skills específicas del proyecto | `docs/examples/project-guidelines-template.md` |

### Política de Adaptación de Skills

Si estás adaptando una idea de otro repo, plugin, harness o pack de prompts personal, lee la [Política de Adaptación de Skills](../skill-adaptation-policy.md) antes de abrir el PR.

Versión corta:

- copia la idea subyacente, no la identidad del producto externo
- renombra la skill cuando ECC cambie o amplíe materialmente la superficie
- prefiere reglas, skills, scripts y MCPs nativos de ECC sobre nuevas dependencias de terceros por defecto
- no publiques una skill cuyo valor principal sea indicarle a los usuarios que instalen un paquete no verificado

### Lista de Verificación de Skills

- [ ] Enfocada en un dominio/tecnología (no demasiado amplia)
- [ ] Incluye sección "Cuándo Activar" para activación automática
- [ ] Incluye ejemplos de código prácticos y reutilizables
- [ ] Muestra anti-patrones (qué NO hacer)
- [ ] Menos de 500 líneas (800 máx)
- [ ] Usa encabezados de sección claros
- [ ] Probada con Claude Code
- [ ] Enlaza a skills relacionadas
- [ ] Sin datos sensibles (claves de API, tokens, rutas)
- [ ] El frontmatter declara `name:` coincidiendo con el nombre del directorio
- [ ] El `description:` del frontmatter es una cadena en línea o escalar plegado (`>`) — no un bloque literal (`|`, `|-` o `|+`), que preserva los saltos de línea internos y rompe los renderizadores de tablas planas

### Skills de Ejemplo

| Skill | Categoría | Propósito |
|-------|----------|---------|
| `coding-standards/` | Estándares de Lenguaje | Patrones de TypeScript/JavaScript |
| `frontend-patterns/` | Patrones de Framework | Mejores prácticas de React y Next.js |
| `backend-patterns/` | Patrones de Framework | Patrones de API y base de datos |
| `security-review/` | Conocimiento de Dominio | Lista de verificación de seguridad |
| `tdd-workflow/` | Flujo de Trabajo | Proceso de desarrollo guiado por pruebas |
| `docs/examples/project-guidelines-template.md` | Plantilla | Plantilla de skill específica del proyecto |

---

## Contribuir Agentes

Los agentes son asistentes especializados invocados mediante la herramienta Task.

### Ubicación del Archivo

```
agents/nombre-de-tu-agente.md
```

### Plantilla de Agente

```markdown
---
name: nombre-de-tu-agente
description: Qué hace este agente y cuándo Claude debería invocarlo. ¡Sé específico!
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
---

Eres un especialista en [rol].

## Tu Rol

- Responsabilidad principal
- Responsabilidad secundaria
- Qué NO haces (límites)

## Flujo de Trabajo

### Paso 1: Comprender
Cómo abordas la tarea.

### Paso 2: Ejecutar
Cómo realizas el trabajo.

### Paso 3: Verificar
Cómo validas los resultados.

## Formato de Salida

Qué devuelves al usuario.

## Ejemplos

### Ejemplo: [Escenario]
Entrada: [qué proporciona el usuario]
Acción: [qué haces]
Salida: [qué devuelves]
```

### Campos del Agente

| Campo | Descripción | Opciones |
|-------|-------------|---------|
| `name` | Minúsculas, con guiones | `code-reviewer` |
| `description` | Usado para decidir cuándo invocar | ¡Sé específico! |
| `tools` | Solo lo que se necesita | `Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task`, o nombres de herramientas MCP (por ejemplo `mcp__context7__resolve-library-id`, `mcp__context7__query-docs`) cuando el agente usa MCP |
| `model` | Nivel de complejidad | `haiku` (simple), `sonnet` (codificación), `opus` (complejo) |

### Agentes de Ejemplo

| Agente | Propósito |
|-------|---------|
| `tdd-guide.md` | Desarrollo guiado por pruebas |
| `code-reviewer.md` | Revisión de código |
| `security-reviewer.md` | Análisis de seguridad |
| `build-error-resolver.md` | Corregir errores de build |

---

## Contribuir Hooks

Los hooks son comportamientos automáticos disparados por eventos de Claude Code.

### Ubicación del Archivo

```
hooks/hooks.json
```

### Tipos de Hook

| Tipo | Disparador | Caso de Uso |
|------|---------|----------|
| `PreToolUse` | Antes de que ejecute la herramienta | Validar, advertir, bloquear |
| `PostToolUse` | Después de que ejecute la herramienta | Formatear, verificar, notificar |
| `SessionStart` | Comienza la sesión | Cargar contexto |
| `Stop` | Termina la sesión | Limpieza, auditoría |

### Formato de Hook

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "tool == \"Bash\" && tool_input.command matches \"rm -rf /\"",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Hook] BLOQUEADO: Comando peligroso' && exit 1"
          }
        ],
        "description": "Bloquear comandos rm peligrosos"
      }
    ]
  }
}
```

### Sintaxis del Matcher

```javascript
// Coincidir con herramientas específicas
tool == "Bash"
tool == "Edit"
tool == "Write"

// Coincidir con patrones de entrada
tool_input.command matches "npm install"
tool_input.file_path matches "\\.tsx?$"

// Combinar condiciones
tool == "Bash" && tool_input.command matches "git push"
```

### Lista de Verificación de Hooks

- [ ] El matcher es específico (no demasiado amplio)
- [ ] Incluye mensajes de error/info claros
- [ ] Usa códigos de salida correctos (`exit 1` bloquea, `exit 0` permite)
- [ ] Probado exhaustivamente
- [ ] Tiene descripción

---

## Contribuir Comandos

Los comandos son acciones invocadas por el usuario con `/nombre-del-comando`.

### Ubicación del Archivo

```
commands/tu-comando.md
```

### Plantilla de Comando

```markdown
---
description: Descripción breve mostrada en /help
---

# Nombre del Comando

## Propósito

Qué hace este comando.

## Uso

\`\`\`
/tu-comando [args]
\`\`\`

## Flujo de Trabajo

1. Primer paso
2. Segundo paso
3. Paso final

## Salida

Qué recibe el usuario.
```

---

## MCP y Documentación (por ejemplo, Context7)

Las skills y los agentes pueden usar herramientas **MCP (Model Context Protocol)** para obtener datos actualizados en lugar de depender solo de los datos de entrenamiento. Esto es especialmente útil para documentación.

- **Context7** es un servidor MCP que expone `resolve-library-id` y `query-docs`. Úsalo cuando el usuario pregunte sobre bibliotecas, frameworks o APIs para que las respuestas reflejen la documentación y ejemplos de código actuales.
- Al contribuir **skills** que dependen de documentación en vivo (por ejemplo, configuración, uso de API), describe cómo usar las herramientas MCP relevantes (por ejemplo, resolver el ID de la biblioteca, luego consultar documentos) y apunta a la skill `documentation-lookup` o Context7 como el patrón.
- Al contribuir **agentes** que responden preguntas de documentación/API, incluye los nombres de herramientas MCP de Context7 (por ejemplo, `mcp__context7__resolve-library-id`, `mcp__context7__query-docs`) en las herramientas del agente y documenta el flujo de trabajo resolver → consultar.
- **mcp-configs/mcp-servers.json** incluye una entrada de Context7; los usuarios la habilitan en su harness (por ejemplo, Claude Code, Cursor) para usar la skill de búsqueda de documentación (en `skills/documentation-lookup/`) y el comando `/docs`.

---

## Cross-Harness y Traducciones

### Subconjuntos de Skills (Codex y Cursor)

ECC incluye subconjuntos de skills para otros harnesses:

- **Codex:** `.agents/skills/` — las skills listadas en `agents/openai.yaml` son cargadas por Codex.
- **Cursor:** `.cursor/skills/` — un subconjunto de skills está empaquetado para Cursor.

Cuando **añades una nueva skill** que debería estar disponible en Codex o Cursor:

1. Añade la skill bajo `skills/nombre-de-tu-skill/` como de costumbre.
2. Si debería estar disponible en **Codex**, añádela a `.agents/skills/` (copia el directorio de la skill o añade una referencia) y asegúrate de que esté referenciada en `agents/openai.yaml` si es necesario.
3. Si debería estar disponible en **Cursor**, añádela bajo `.cursor/skills/` según el diseño de Cursor.

Consulta las skills existentes en esos directorios para la estructura esperada. Mantener estos subconjuntos sincronizados es manual; menciona en tu PR si los actualizaste.

### Traducciones

Las traducciones viven bajo `docs/` (por ejemplo, `docs/zh-CN`, `docs/zh-TW`, `docs/ja-JP`). Si cambias agentes, comandos o skills que están traducidos, considera actualizar los archivos de traducción correspondientes o abrir un issue para que los mantenedores o traductores puedan actualizarlos.

---

## Proceso de Pull Request

### 1. Formato del Título del PR

```
feat(skills): add rust-patterns skill
feat(agents): add api-designer agent
feat(hooks): add auto-format hook
fix(skills): update React patterns
docs: improve contributing guide
```

### 2. Descripción del PR

```markdown
## Resumen
Qué estás añadiendo y por qué.

## Tipo
- [ ] Skill
- [ ] Agente
- [ ] Hook
- [ ] Comando

## Pruebas
Cómo lo probaste.

## Lista de Verificación
- [ ] Sigue las directrices de formato
- [ ] Probado con Claude Code
- [ ] Sin información sensible (claves de API, rutas)
- [ ] Descripciones claras
```

### 3. Proceso de Revisión

1. Los mantenedores revisan en 48 horas
2. Atiende el feedback si se solicita
3. Una vez aprobado, se fusiona a main

---

## Directrices

### Haz
- Mantén las contribuciones enfocadas y modulares
- Incluye descripciones claras
- Prueba antes de enviar
- Sigue los patrones existentes
- Documenta las dependencias

### No Hagas
- Incluir datos sensibles (claves de API, tokens, rutas)
- Añadir configuraciones demasiado complejas o de nicho
- Enviar contribuciones sin probar
- Crear duplicados de funcionalidad existente

---

## Nombres de Archivo

- Usa minúsculas con guiones: `python-reviewer.md`
- Sé descriptivo: `tdd-workflow.md` no `workflow.md`
- Haz coincidir el nombre con el nombre del archivo

---

## ¿Preguntas?

- **Issues:** [github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues)
- **X/Twitter:** [@affaanmustafa](https://x.com/affaanmustafa)

---

¡Gracias por contribuir! Construyamos juntos un gran recurso.