# Docs

> Reglas de documentación - Markdown, README, JSDoc, TypeDoc, changelogs, convenciones de escritura técnica

- **Type:** Skill
- **Install:** `agentstack add skill-14bryanespinoza-agent-stack-docs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [14BryanEspinoza](https://agentstack.voostack.com/s/14bryanespinoza)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [14BryanEspinoza](https://github.com/14BryanEspinoza)
- **Source:** https://github.com/14BryanEspinoza/agent-stack/tree/agent-stack/skills/docs

## Install

```sh
agentstack add skill-14bryanespinoza-agent-stack-docs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Documentación — Reglas y Convenciones

---

## 1. Filosofía

1. **Documentación como código** — Los docs viven en el repo, se versionan, se revisan en PRs y siguen las mismas convenciones que el código.
2. **Valor sobre cantidad** — Cada documento responde a una pregunta concreta. Sin relleno, sin contenido duplicado, sin documentación por documentar.
3. **Legibilidad** — El lenguaje debe ser claro, directo y adaptado a la audiencia. Priorizar ejemplos sobre descripciones abstractas.
4. **Mantenibilidad** — Los docs se mantienen junto al código. Si cambia la API, cambia la documentación en el mismo PR.
5. **Progressive disclosure** — Información de lo general a lo específico. README primero, luego guías, luego API reference.

---

## 2. Estructura de Documentos

### README.md (esencial)

````markdown
# Nombre del Proyecto

Descripción breve: qué hace, para quién, por qué existe.

## Instalación

```bash
npm install mi-paquete
```
````

## Uso rápido

```js
import { algo } from "mi-paquete";
algo();
```

## API

### `función(opciones)`

Descripción de la función, parámetros, valor de retorno.

| Parámetro  | Tipo     | Default | Descripción        |
| ---------- | -------- | ------- | ------------------ |
| `opciones` | `Object` | `{}`    | Opciones de Config |

## Contribuir

Ver [CONTRIBUTING.md](./CONTRIBUTING.md)

## Licencia

MIT © 2026

````text

### Componentes de un buen README

| Sección         | Obligatorio | Propósito                          |
| --------------- | ----------- | ---------------------------------- |
| Título + badges | ✅          | Identidad y estado del proyecto    |
| Descripción     | ✅          | Propósito y audiencia              |
| Instalación     | ✅          | Primeros pasos                     |
| Uso rápido      | ✅          | Ejemplo mínimo funcional           |
| API             | ⚠️ condicional | Referencia detallada           |
| Contribuir      | ⚠️ condicional | Guía para colaboradores        |
| Licencia        | ✅          | Términos de uso                    |
| Changelog       | ⚠️ condicional | Historial de cambios           |

### CONTRIBUTING.md

```markdown
# Contribuyendo al proyecto

## Proceso

1. Fork el repo
2. Crea una rama: `git checkout -b feature/42-nombre`
3. Haz cambios en commits atómicos
4. Asegúrate de que los tests pasen
5. Abre un Pull Request

## Convenciones

- Commits: [Conventional Commits](../git/SKILL.md)
- Código: sigue el estilo del proyecto
- Tests: incluye tests para nuevas funcionalidades
- Documentación: actualiza docs si cambia la API
````

### CODE_OF_CONDUCT.md

```markdown
# Código de Conducta

## Compromiso

Nos comprometemos a hacer de la participación en este proyecto
una experiencia libre de acoso para todos.

## Comportamiento esperado

- Usar lenguaje inclusivo y respetuoso
- Aceptar críticas constructivas
- Enfocarse en lo que es mejor para la comunidad

## Comportamiento inaceptable

- Comentarios sexuales o violentos
- Trolling, insultos, ataques personales
- Acoso público o privado

## Aplicación

Reportar incidentes a [email].
```

---

## 3. Markdown

### Sintaxis esencial

```markdown
# H1

## H2

### H3

**negrita** _cursiva_ `código inline`

[link](https://ejemplo.com)

- Lista no ordenada
- Item

1. Lista ordenada
2. Item

> Cita

` ``js
console.log("código bloque"); ` ``

| Tabla | Columna 2 |
| ----- | --------- |
| Dato  | Dato      |

---
```

### Reglas de formato

- Una línea en blanco antes/después de headings
- Una línea en blanco antes/después de listas y bloques de código
- Líneas máximo 80 caracteres en párrafos (no aplica a tablas ni bloques de código)
- Sin espacios al final de línea
- Listas con `-` (no `*`)
- Bloques de código siempre con lenguaje especificado

### Frontmatter YAML

```yaml
---
title: Título del documento
description: Descripción breve
date: 2026-07-15
author: Nombre
---
```

### Admonitions (soportado por varios renderers)

```markdown
> **Nota:** Información adicional importante.

> **Advertencia:** Esto puede causar problemas.

> **Peligro:** Esto es crítico.
```

### Links internos

```markdown
[Ver sección](#sección)
[Referencia a otro documento](./CONTRIBUTING.md)
[Link absoluto](/docs/api.md)
```

---

## 4. Documentación de API

### JSDoc

```js
/**
 * Calcula el total con impuestos.
 *
 * @param {number} subtotal - Monto sin impuestos
 * @param {number} [taxRate=0.16] - Tasa de impuesto (default 16%)
 * @returns {number} Total con impuestos incluidos
 * @throws {TypeError} Si subtotal no es un número
 *
 * @example
 * const total = calcularTotal(100, 0.16)
 * // → 116
 */
export function calcularTotal(subtotal, taxRate = 0.16) {
  if (typeof subtotal !== "number") {
    throw new TypeError("subtotal debe ser un número");
  }
  return subtotal * (1 + taxRate);
}
```

#### Tags JSDoc esenciales

| Tag           | Uso                                       |
| ------------- | ----------------------------------------- |
| `@param`      | Descripción de parámetro (+ tipo)         |
| `@returns`    | Valor de retorno (+ tipo)                 |
| `@throws`     | Error que puede lanzar                    |
| `@example`    | Ejemplo de uso (seguido de bloque código) |
| `@deprecated` | Marca como obsoleto                       |
| `@see`        | Referencia a otro elemento                |
| `@typedef`    | Definición de tipo personalizado          |
| `@property`   | Propiedad de un tipo                      |
| `@template`   | Parámetro genérico (TypeScript)           |

```js
/**
 * @typedef {Object} User
 * @property {number} id - Identificador único
 * @property {string} name - Nombre completo
 * @property {string} email - Correo electrónico
 */

/**
 * @template T
 * @param {T} item
 * @returns {T}
 */
function identity(item) {
  return item;
}
```

### TypeDoc

```ts
interface Config {
  /** Puerto del servidor */
  port: number;
  /** Host donde escuchar */
  host: string;
}

/**
 * Inicia el servidor con la configuración dada.
 *
 * @param config - Opciones de configuración
 * @returns Una promesa que resuelve cuando el servidor inicia
 */
async function startServer(config: Config): Promise;
```

---

## 5. Changelog

### Formato (Keep a Changelog)

```markdown
# Changelog

## [1.2.0] - 2026-07-15

### Added

- Nueva funcionalidad X
- Soporte para Y

### Changed

- Mejorada la performance de Z
- Actualizada dependencia A a v2

### Deprecated

- Función `foo()` será eliminada en v2

### Removed

- Eliminado soporte para navegadores antiguos

### Fixed

- Corregido bug en login (#42)

### Security

- Parcheada vulnerabilidad CVE-2026-XXXX

## [1.1.0] - 2026-06-01

### Added

- Feature menor

## [1.0.0] - 2026-01-15

### Added

- Release inicial
```

### Reglas del Changelog

- **Mantenerlo manual** — No generar automáticamente desde commits (el resultado es ruidoso)
- **Agrupar por tipo** — `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`
- **Referenciar issues/PRs** — `(#42)` al final de cada línea
- **Fecha en ISO 8601** — `YYYY-MM-DD`
- **SemVer** — La versión del changelog debe coincidir con los tags de git
- **Unreleased section** — Mantener una sección `[Unreleased]` en desarrollo

---

## 6. Documentación Técnica

### Guías vs Referencia

| Tipo           | Propósito                                 | Audiencia          | Formato          |
| -------------- | ----------------------------------------- | ------------------ | ---------------- |
| **Guía**       | Cómo lograr un objetivo paso a paso       | Usuarios nuevos    | Tutorial, how-to |
| **Ref**        | Descripción completa de API, config, etc. | Usuarios avanzados | Reference        |
| **Conceptual** | Explicación de conceptos y arquitectura   | Todos              | Explicación      |

### Ejemplo: Guía de inicio rápido

````markdown
# Guía: Configurar autenticación

En esta guía agregarás autenticación por email/password.

## Prerrequisitos

- Node.js 22+
- Proyecto inicializado

## Paso 1: Instalar dependencias

```bash
npm install @auth/core
```
````

## Paso 2: Configurar proveedor

```js
import { Auth } from "@auth/core";

const auth = new Auth({
  provider: "credentials",
  // ...
});
```

### Ejemplo: Documentación conceptual

```markdown
# Arquitectura del sistema

## Capas

1. **Presentación** — Componentes UI (React/Vanilla)
2. **Lógica de negocio** — Hooks, servicios, utils
3. **Acceso a datos** — API calls, caché, almacenamiento local

## Flujo de datos

[Diagrama de flujo o descripción textual]

Los datos viajan de la capa de datos a la presentación
a través de hooks personalizados que manejan loading, error y éxito.
```

---

## 7. Diagramas (Mermaid)

Incorporar diagramas en los docs usando Mermaid (soportado por GitHub, GitLab y renderers MD):

```mermaid
flowchart TD
    A[Inicio] --> B{¿Autenticado?}
    B -->|Sí| C[Dashboard]
    B -->|No| D[Login]
    D --> C
```

```mermaid
sequenceDiagram
    User->>API: POST /login
    API->>DB: Verificar credenciales
    DB-->>API: Usuario válido
    API-->>User: Token JWT
```

```mermaid
graph LR
    A[HTML] --> B[CSS]
    A --> C[JavaScript]
    B --> D[DOM]
    C --> D
```

### Tipos de diagrama recomendados

| Tipo              | Para qué usar                             |
| ----------------- | ----------------------------------------- |
| `flowchart`       | Flujos de proceso, decisiones, pipelines  |
| `sequenceDiagram` | Interacciones entre componentes/servicios |
| `classDiagram`    | Estructuras de clases y relaciones        |
| `stateDiagram`    | Estados de un componente o proceso        |
| `graph`           | Relaciones generales entre entidades      |
| `gantt`           | Cronogramas y planificación               |

---

## 8. Documentación de Componentes (Frontend)

````markdown
# Componente: Button

Botón reutilizable con variantes visuales y estados.

## Propiedades

| Prop       | Tipo                                  | Default     | Descripción          |
| ---------- | ------------------------------------- | ----------- | -------------------- |
| `variant`  | `'primary' \| 'secondary' \| 'ghost'` | `'primary'` | Estilo visual        |
| `size`     | `'sm' \| 'md' \| 'lg'`                | `'md'`      | Tamaño del botón     |
| `disabled` | `boolean`                             | `false`     | Estado deshabilitado |
| `loading`  | `boolean`                             | `false`     | Muestra spinner      |
| `onClick`  | `() => void`                          | —           | Handler de click     |

## Estados

| Estado       | Comportamiento                           |
| ------------ | ---------------------------------------- |
| **Normal**   | Estilo según variant                     |
| **Hover**    | Darken 10% del color base                |
| **Active**   | Darken 20% del color base                |
| **Disabled** | Opacidad 50%, sin hover, sin click       |
| **Loading**  | Muestra spinner, deshabilita interacción |
| **Focus**    | Outline visible (accesibilidad)          |

## Ejemplos

### Botón primario

```html
Guardar
```
````

### Botón con loading

```html

   Cargando...

```

---

## 9. Herramientas

### TypeDoc Tools

```bash
# Instalación
npm install -D typedoc

# Config (typedoc.json)
{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "excludePrivate": true,
  "excludeProtected": true,
  "theme": "default"
}

# Generar
npx typedoc
```

### JSDoc Tools

```bash
# Generar documentación desde JSDoc
npm install -D jsdoc

# Config (jsdoc.json)
{
  "source": { "include": ["src"] },
  "opts": { "destination": "docs/api" }
}

# Generar
npx jsdoc -c jsdoc.json
```

### Vitepress (documentación de proyecto)

```bash
npm install -D vitepress

# Estructura
docs/
  .vitepress/
    config.js
  index.md
  guide/
    getting-started.md
  api/
    reference.md

# Config (.vitepress/config.js)
export default {
  title: 'Mi Proyecto',
  description: 'Documentación del proyecto',
  themeConfig: {
    nav: [
      { text: 'Guía', link: '/guide/' },
      { text: 'API', link: '/api/' }
    ],
    sidebar: [
      { text: 'Introducción', link: '/guide/' }
    ]
  }
}
```

### Markdown lint

```bash
npm install -D markdownlint-cli

# Config (.markdownlint.json)
{
  "MD013": { "line_length": 80 },
  "MD033": false,
  "MD041": false
}

# Ejecutar
npx markdownlint '**/*.md' --ignore node_modules
```

---

## 10. Documentación en PRs

### Descripción de PR

```markdown
## Descripción

## Cambios principales

- Agrega endpoint de login
- Actualiza documentación de API
- Corrige tipografía en README

## Documentación relacionada

- [ ] README actualizado
- [ ] JSDoc agregado a funciones nuevas
- [ ] Changelog actualizado
- [ ] API docs actualizadas

## Breaking changes

## Closes

Closes #42
```

### Reglas para docs en PRs

- **README**: Actualizar si cambia instalación, uso o API pública
- **JSDoc/TypeDoc**: Toda función pública debe estar documentada
- **Changelog**: Agregar entrada en `[Unreleased]` con tipo correspondiente
- **API docs**: Si se agrega/modifica un endpoint, actualizar la referencia

---

## 11. Estilo de Escritura

### Lenguaje

- **Español** para proyectos dirigidos a hispanohablantes
- **Inglés** para proyectos open-source internacionales (por defecto en la skill git)
- **No mezclar idiomas** en un mismo documento
- **Tú** (informal) en lugar de "usted" o "el usuario"

### Convenciones

```markdown
# ✅ Bueno

Haz clic en Guardar para continuar.

# ❌ Malo

El usuario debería hacer clic en el botón de Guardar para continuar.

# ✅ Bueno

Crea un archivo `.env` con las siguientes variables:

# ❌ Malo

Deberías crear un archivo .env con las siguientes variables de entorno.
```

### Voz activa

```markdown
# ✅ Bueno

El hook `useAuth` retorna el usuario autenticado.

# ❌ Malo

El usuario autenticado es retornado por el hook `useAuth`.
```

### Ejemplos ejecutables

Todos los ejemplos de código deben:

- Poder copiarse y pegarse para funcionar (sin placeholders no obvios)
- Incluir imports completos (no fragmentos)
- Tener comentarios explicativos solo si es necesario

---

## 12. Documentación de Configuración

````markdown
# Configuración

## Variables de entorno

| Variable       | Default       | Obligatoria | Descripción          |
| -------------- | ------------- | ----------- | -------------------- |
| `DATABASE_URL` | —             | ✅          | URL de conexión a DB |
| `PORT`         | `3000`        | ❌          | Puerto del servidor  |
| `NODE_ENV`     | `development` | ❌          | Entorno de ejecución |

## Archivo de configuración

```json
{
  "api": {
    "baseUrl": "https://api.ejemplo.com",
    "timeout": 5000
  },
  "ui": {
    "theme": "dark",
    "language": "es"
  }
}
```
````

### Ejemplo de archivo .env.example

```bash
# Copiar a .env y completar valores
DATABASE_URL=postgresql://user:pass@localhost:5432/db
PORT=3000
API_KEY=tu-api-key
```

---

## 13. Prohibiciones

- ❌ **NO** documentar lo obvio (`// suma dos números` en `function sum(a, b)`)
- ❌ No dejar secciones TODO/FIXME en docs publicados
- ❌ No usar `click here` como link text
- ❌ No mezclar inglés y español en el mismo documento
- ❌ No documentar implementación privada (solo API pública)
- ❌ No generar changelogs automatizados sin editar (son ruidosos)
- ❌ No asumir conocimiento previo del lector sin contexto
- ❌ No incluir información sensible (API keys, passwords) en ejemplos
- ❌ No usar `` o HTML en Markdown salvo casos justificados
- ❌ No dejar bloques de código sin lenguaje especificado
- ❌ No docs desactualizados — si el código cambia, los docs cambian

---

## 14. Referencias

> **Nota:** Para commits y PRs, ver [Git](../git/SKILL.md)

---

Última actualización: 2026-07

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [14BryanEspinoza](https://github.com/14BryanEspinoza)
- **Source:** [14BryanEspinoza/agent-stack](https://github.com/14BryanEspinoza/agent-stack)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-14bryanespinoza-agent-stack-docs
- Seller: https://agentstack.voostack.com/s/14bryanespinoza
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.