---
name: github-repo-docs
description: >-
  Redacta y revisa documentación de repositorios en GitHub (README, CONTRIBUTING,
  licencia, plantillas de issues y PRs, checklist de repo). Usar cuando el usuario
  pida documentar un proyecto en GitHub, mejorar el README, preparar el repo para
  colaboradores o revisar si el repositorio está en buen estado.
disable-model-invocation: true
---

# Documentación de repositorios en GitHub

## Cuándo aplicar esta skill

Al crear o editar `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, plantillas en `.github/`, o al auditar qué falta para que un repo sea claro y mantenible.

## Tono y estilo

- No uses emojis en títulos ni en el cuerpo de la documentación que generes o propongas.
- Evita badges decorativos que no aporten información (por ejemplo filas de badges solo por estética). Si un badge enlaza a CI o a un paquete publicado, está bien.
- Prefiere oraciones cortas y voz activa. Segunda persona ("instala…", "ejecuta…") o impersonal ("se requiere Node 20") según el público.
- No rellenes con frases genéricas ("solución robusta", "de nueva generación", "revolucionario"). Di qué hace el proyecto, para quién y con qué limitaciones reales.
- Ordena el README para que alguien nuevo entienda el valor y pueda arrancar en pocos minutos antes de entrar en detalle técnico profundo.
- Ajusta el nivel técnico: CLI, librería, API, app web o monorepo no se explican igual.

## Estructura mínima del README

Usa esta estructura como guía; omite secciones que no apliquen y nómbralas solo si añaden valor.

1. **Nombre del proyecto** como título y un párrafo (o dos) que diga qué problema resuelve y para quién es útil.
2. **Requisitos**: versiones concretas de runtime, sistema operativo o herramientas cuando importe.
3. **Instalación**: clonar, instalar dependencias, pasos mínimos reproducibles.
4. **Uso rápido**: un comando o el ejemplo más pequeño que demuestre que funciona.
5. **Configuración**: variables de entorno, archivos de config; tabla o lista clara. Si hay secretos, documenta `.env.example` sin valores reales.
6. **Desarrollo**: cómo ejecutar tests, lint o build localmente (comandos exactos si existen).
7. **Contribución**: párrafo breve y enlace a `CONTRIBUTING.md` si está en archivo aparte.
8. **Licencia**: cómo se licencia el código y enlace o nombre del archivo `LICENSE`.
9. **Seguridad**: si aplica, enlace a `SECURITY.md` para reporte responsable de vulnerabilidades.

Plantilla mínima (adaptar títulos y secciones al proyecto). Los fences internos van con tres backticks como en cualquier README:

````markdown
# Nombre del proyecto

[Qué hace y para quién. Sin marketing vacío.]

## Requisitos

- …

## Instalación

```bash
git clone …
cd …
# instalar dependencias según el stack
```

## Uso

```bash
# comando mínimo que demuestra el flujo principal
```

## Configuración

| Variable | Descripción | Obligatoria |
|----------|-------------|-------------|
| … | … | … |

## Desarrollo

```bash
# tests o lint
```

## Contribución

Las contribuciones son bienvenidas. Ver [CONTRIBUTING.md](CONTRIBUTING.md).

## Licencia

Ver [LICENSE](LICENSE).

## Seguridad

Ver [SECURITY.md](SECURITY.md).
````

## Checklist: repo en condiciones

Marca mentalmente qué existe y qué falta antes de dar por cerrada la documentación.

**Obligatorio o casi obligatorio para proyectos públicos con colaboración**

- [ ] `README.md` con valor claro, instalación y uso mínimo verificables.
- [ ] `LICENSE` en la raíz y mención en el README.
- [ ] `CONTRIBUTING.md` si esperas PRs externos (flujo de ramas, tests, estilo de commits si el equipo lo usa).

**Muy recomendable**

- [ ] `CHANGELOG.md` o notas claras en **Releases** de GitHub.
- [ ] CI básica documentada en el README (qué corre y qué debe pasar). Badges solo si informan (build, versión publicada).
- [ ] `.github/ISSUE_TEMPLATE` y `pull_request_template.md` cuando haya más de una persona o issues frecuentes.
- [ ] Descripción corta del repo en GitHub, **topics** para búsqueda, URL del sitio o demo si existe.

**Según el tipo de proyecto**

- [ ] `SECURITY.md` si el proyecto es público, tiene dependencias o superficie de ataque no trivial.
- [ ] `.env.example` sin secretos reales.
- [ ] `Dockerfile` o instrucciones de contenedor si el entorno es difícil de reproducir.
- [ ] Documentar ramas (`main`, `develop`) y reglas de merge si no están solo en CONTRIBUTING.

No copies manuales largos de GitHub en la respuesta: indica archivos, propósito y si algo es obligatorio o recomendable según el contexto del repo.

## Recursos adicionales

Para ejemplos de tono (bien vs mal) y checklist por tipo de proyecto (librería, app, monorepo), lee [reference.md](reference.md).