Skill: Documentación técnica por capability
Guía para crear o actualizar documentos técnicos en docs/specs/technical-docs/. Cada documento pertenece a una capability (una capacidad del sistema: facturación, autenticación, catálogo…) y estandariza los modelos de datos, APIs/endpoints, flujos/procesos y diagramas (clases, contexto, contenedores, componentes…) de esa capability, con elementos identificables (MD-XX, API-XX, FL-XX, DG-XX) que las US, TK y WI enlazan como referencia de implementación.
Alcance: este skill produce especificación técnica, no documentación funcional ni código. El valor de negocio y los criterios de aceptación viven en la US (work-define); el plan de implementación vive en las TK/WI (work-plan); las decisiones de arquitectura viven en ADRs (docs/adr/, nunca creados desde aquí). Un documento técnico describe qué forma tienen los modelos, contratos y flujos — no por qué se eligió una tecnología ni cómo se codifica.
La plantilla canónica está en assets/technical-doc-template.md (léela antes de escribir cualquier documento). Los estándares de cada tipo de elemento están en references/element-standards.md.
Subagente
Si el proyecto define el subagente docs-specialist, ejecutar este skill bajo ese subagente. Si no existe en el proyecto:
- Invocación directa por el usuario: ejecutar el flujo normalmente, sin subagente.
- Invocación desde otro skill (
work-define, work-plan): ejecutar este skill bajo un subagente genérico (el de propósito general que exponga el cliente). La delegación siempre ocurre en un subagente — con docs-specialist si existe, genérico si no — para aislar el contexto del skill llamador y que la respuesta final sea solo las referencias devueltas.
Este skill es frecuentemente invocado por otros skills mediante un subagente (work-define al detectar que una US define flujos, modelos o APIs; work-plan cuando una TK/WI menciona elementos técnicos sin especificación). En ese modo, ver Modo delegado.
Mapa de referencias
Carga el archivo correspondiente cuando vayas a ejecutar la tarea; el detalle íntegro vive en references/.
| Necesitas… |
Archivo |
| Flujo paso a paso de crear y actualizar, grilling de preguntas, validación antes de crear, modo delegado, checklist, ejemplos, anti-patrones y handoffs |
references/flow.md |
Estándares de definición de modelos de datos (MD-XX), APIs/endpoints (API-XX), flujos/procesos (FL-XX) y diagramas (DG-XX: clases, contexto, contenedores, componentes): tablas, diagramas Mermaid, ejemplos |
references/element-standards.md |
| Estructura del documento técnico de una capability |
assets/technical-doc-template.md |
Referencias compartidas del plugin
Reglas transversales del catálogo; viven en la raíz del plugin, no en este skill.
Rutas de las referencias compartidas
${PLUGIN_ROOT} es la raíz del plugin instalado (la carpeta que contiene skills/, agents/ y reference/), y toda referencia compartida de este skill se escribe como ${PLUGIN_ROOT}/reference/<archivo>.md. Resolverla así, en este orden: (1) en Claude Code, ${PLUGIN_ROOT} es ${CLAUDE_PLUGIN_ROOT} — comprobar con echo "$CLAUDE_PLUGIN_ROOT" y usar ese valor; (2) en cualquier otro cliente, o si la variable está vacía, la carpeta desde la que se cargó este archivo, dos niveles arriba. El destino de cada enlace markdown (../../reference/…) existe solo para navegar el repositorio en GitHub o en un editor: no resolverlo desde el directorio de trabajo. Nunca buscar reference/ en el proyecto: un <proyecto>/reference/language.md que no existe no es un archivo que falte, es una ruta mal resuelta — corregir la raíz y volver a leer, sin preguntar al usuario ni saltarse la lectura.
Resolución de idioma
Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/language.md.
Las reglas de language.md son obligatorias y tienen prioridad para determinar el idioma de todos los artefactos y mensajes generados por este skill.
No continúes hasta haber leído y aplicado language.md.
Excepción deliberada: los nombres de campos, rutas y payloads no siguen el idioma resuelto — siguen la convención del código existente (ver references/element-standards.md).
Ubicación de archivos
Layout completo del harness e identificadores: ${PLUGIN_ROOT}/reference/artifacts.md.
Lo propio de este skill:
| Artefacto |
Ruta |
| Documento técnico de capability (salida) |
docs/specs/technical-docs/[capability].md |
| Archivos de apoyo (imágenes, esquemas exportados) |
docs/specs/technical-docs/assets/[capability]/ |
| Glosario (opcional) |
docs/specs/glossary.md |
Convenciones
- Un documento por capability. Si el documento de la capability ya existe, se actualiza (se añaden o modifican elementos); nunca crear un segundo documento para la misma capability.
- Nombre de archivo: capability en minúsculas, kebab-case, sin artículos ni palabras vacías. Ejemplos:
facturacion.md, gestion-recetas.md, autenticacion.md.
- Dentro del documento, cada elemento lleva id secuencial por tipo, único en el ámbito de la capability: modelos
MD-01, MD-02, …; APIs API-01, API-02, …; flujos FL-01, FL-02, …; diagramas DG-01, DG-02, …. No renumerar elementos existentes: los ids son estables porque otras historias y tareas ya pueden enlazarlos.
- Cada elemento es un encabezado
### con el formato ### MD-01: Nombre, precedido de su ancla explícita <a id="md-01"></a> en la línea inmediatamente anterior. La referencia que se cita es esa: docs/specs/technical-docs/facturacion.md#md-01 — el id en minúsculas, sin el nombre. Nunca un ancla derivada del título (#md-01-factura): depende del renderizador y se rompe al renombrar el elemento. Ver Por qué el ancla no se deriva del título.
- El documento lleva fecha de creación y última actualización. Las lagunas abiertas se registran en Observaciones del propio documento.
Modos de invocación
| Modo |
Quién invoca |
Entrada típica |
Salida esperada |
| Directo |
El usuario |
«Documenta el modelo de factura», «especifica la API de pagos», «dame más detalle del flujo de aprobación de la TK-004» |
Documento creado/actualizado + resumen al usuario + oferta de enlazarlo desde la US/TK/WI relacionada |
| Delegado |
work-define o work-plan vía subagente |
Contexto de la US/TK/WI + los elementos técnicos a especificar |
Documento creado/actualizado y, como respuesta final del subagente, la lista de referencias (ruta relativa + ancla #<id> de cada elemento) para que el skill llamador las agregue a la sección Referencias del artefacto |
En modo delegado, el grilling de preguntas se dirige igualmente al usuario (el subagente hereda la herramienta de preguntas estructuradas); si el entorno no permite preguntar, documentar las lagunas en Observaciones y reportarlas en la respuesta final en lugar de inventar. En modo directo, si el entorno tampoco permite preguntar (p. ej. sesión desatendida/programada sin nadie que responda en el momento), aplicar el mismo criterio: no inventar, documentar cada laguna en Observaciones citando el elemento afectado, y destacarlas de forma prominente al principio del resumen final — a diferencia del modo delegado, aquí no hay un skill llamador que las recoja, así que es el propio resumen al usuario el único lugar donde quedan visibles.
Cómo preguntar al usuario (grilling)
Mecanismo, ritmo y fallback compartidos: ${PLUGIN_ROOT}/reference/asking.md.
Cada vez que este skill o sus referencias digan preguntar, pedir, confirmar, validar o sugerir algo al usuario, asume ese mecanismo; no se repite allí.
Recopilación inicial (antes de redactar): si hay más de tres lagunas, encadenar tandas hasta agotarlas o hasta que el usuario indique que lo restante quede como Observación.
No repreguntar lo que ya está respondido en la US/TK/WI de origen o en el documento técnico existente.
El detalle de qué preguntar por tipo de elemento (campos sin tipo, códigos de error sin definir, ramas de flujo ambiguas…) está en references/flow.md.
Información requerida antes de redactar
No inventar nada — si un dato no es explícito ni inferible del repo, preguntar al usuario (o reportarlo como laguna, en cualquier modo, cuando el entorno no permite preguntar — ver Modos de invocación).
| Dato |
Cómo obtenerlo |
Si no está disponible |
| Capability a la que pertenece el elemento |
Indicada por el usuario/skill llamador, o inferible de la US/TK/WI y de los documentos existentes en technical-docs/ |
Preguntar; proponer opciones a partir de los documentos existentes antes de crear una capability nueva |
| Tipo(s) de elemento (modelo, API, flujo, diagrama) |
Del pedido o del contenido de la US/TK/WI |
Preguntar |
| Contenido de cada elemento (campos, contratos, pasos) |
Del input recibido, del código existente del repo, o de la US/TK/WI de origen |
Grilling de preguntas; lo irresoluble queda en Observaciones |
| Artefacto(s) que lo consumirán (US/TK/WI) |
Del contexto o del skill llamador |
Opcional en modo directo; si existe, ofrecer enlazar la referencia al terminar |
Flujo (resumen)
El procedimiento completo está en references/flow.md. Síntesis:
- Crear/actualizar: resolver capability → leer el documento existente si lo hay → detectar lagunas y hacer el grilling → redactar los elementos con
assets/technical-doc-template.md y los estándares de references/element-standards.md → asignar ids estables → actualizar la fecha de última actualización → glosario si aplica.
- Enlazar: en modo delegado, devolver las referencias (ruta + ancla
#<id>) al skill llamador; en modo directo, ofrecer agregar la referencia a la sección Referencias de la US/TK/WI relacionada.
- Cierre: si quedaron lagunas en Observaciones, ofrecerle al usuario las preguntas que las cerrarían (misma mecánica de grilling).
Mensaje al usuario
Solo resultados y lo que el usuario debe saber o decidir. No incluir razonamiento interno ni narración del trabajo en curso («leí la US», «creé el archivo»). Si hay pendientes, listarlos agrupados por elemento (MD-XX, API-XX, FL-XX, DG-XX). En modo delegado, la respuesta final del subagente es datos para el skill llamador (rutas y anclas #<id>), no prosa para el humano.
1---2name: design-define3description: Crear o actualizar documentación técnica (modelos de datos, APIs/endpoints, flujos/procesos, diagramas de clases/contexto/contenedores/componentes) en docs/specs/technical-docs/, organizada por capability, para que sirva como referencia de implementación de historias de usuario (US-XXX), tareas técnicas (TK-XXX) y tareas de mantenimiento (WI-XXX). Activar cuando el usuario pida documentar o especificar un modelo, entidad, DTO, contrato de API, endpoint, flujo, proceso técnico o un diagrama (clases, C4, arquitectura de la capability); cuando pida «más detalle» sobre un elemento técnico sin especificación mencionado en una US, TK o WI; o cuando otro skill (work-define, work-plan) delegue la creación de la especificación técnica. También activar con «/design-define», «documento técnico», «technical doc», «especificación técnica» o «diseño técnico», aunque el usuario no nombre la capability.4license: MIT5---67# Skill: Documentación técnica por capability89Guía para **crear o actualizar** documentos técnicos en `docs/specs/technical-docs/`. Cada documento pertenece a una **capability** (una capacidad del sistema: facturación, autenticación, catálogo…) y estandariza los **modelos de datos**, **APIs/endpoints**, **flujos/procesos** y **diagramas** (clases, contexto, contenedores, componentes…) de esa capability, con elementos identificables (`MD-XX`, `API-XX`, `FL-XX`, `DG-XX`) que las US, TK y WI enlazan como referencia de implementación.1011> **Alcance:** este skill produce **especificación técnica**, no documentación funcional ni código. El valor de negocio y los criterios de aceptación viven en la US (`work-define`); el plan de implementación vive en las TK/WI (`work-plan`); las decisiones de arquitectura viven en ADRs (`docs/adr/`, nunca creados desde aquí). Un documento técnico describe **qué forma tienen** los modelos, contratos y flujos — no por qué se eligió una tecnología ni cómo se codifica.1213La plantilla canónica está en `assets/technical-doc-template.md` (léela antes de escribir cualquier documento). Los estándares de cada tipo de elemento están en `references/element-standards.md`.1415## Subagente1617**Si el proyecto define el subagente `docs-specialist`, ejecutar este skill bajo ese subagente.** Si no existe en el proyecto:1819- **Invocación directa por el usuario:** ejecutar el flujo normalmente, sin subagente.20- **Invocación desde otro skill** (`work-define`, `work-plan`): ejecutar este skill bajo un **subagente genérico** (el de propósito general que exponga el cliente). La delegación siempre ocurre en un subagente — con `docs-specialist` si existe, genérico si no — para aislar el contexto del skill llamador y que la respuesta final sea solo las referencias devueltas.2122Este skill es frecuentemente **invocado por otros skills mediante un subagente** (`work-define` al detectar que una US define flujos, modelos o APIs; `work-plan` cuando una TK/WI menciona elementos técnicos sin especificación). En ese modo, ver [Modo delegado](#modos-de-invocación).2324---2526## Mapa de referencias2728Carga el archivo correspondiente cuando vayas a ejecutar la tarea; el detalle íntegro vive en `references/`.2930| Necesitas… | Archivo |31| ---------- | ------- |32| Flujo paso a paso de **crear** y **actualizar**, grilling de preguntas, validación antes de crear, modo delegado, checklist, ejemplos, anti-patrones y handoffs | [`references/flow.md`](references/flow.md) |33| Estándares de definición de **modelos de datos** (`MD-XX`), **APIs/endpoints** (`API-XX`), **flujos/procesos** (`FL-XX`) y **diagramas** (`DG-XX`: clases, contexto, contenedores, componentes): tablas, diagramas Mermaid, ejemplos | [`references/element-standards.md`](references/element-standards.md) |34| Estructura del documento técnico de una capability | `assets/technical-doc-template.md` |353637### Referencias compartidas del plugin3839Reglas transversales del catálogo; viven en la raíz del plugin, no en este skill.4041- [`${PLUGIN_ROOT}/reference/language.md`](../../reference/language.md): **Idioma** — resolución obligatoria del idioma de artefactos y mensajes. *Lectura obligatoria antes de ejecutar el skill.*42- [`${PLUGIN_ROOT}/reference/artifacts.md`](../../reference/artifacts.md): **Artefactos** — rutas del harness, identificadores, archivado. *Al resolver una ruta o calcular un ID.*4344---4546## Rutas de las referencias compartidas4748`${PLUGIN_ROOT}` es la **raíz del plugin instalado** (la carpeta que contiene `skills/`, `agents/` y `reference/`), y toda referencia compartida de este skill se escribe como `${PLUGIN_ROOT}/reference/<archivo>.md`. Resolverla así, **en este orden**: (1) en Claude Code, `${PLUGIN_ROOT}` **es** `${CLAUDE_PLUGIN_ROOT}` — comprobar con `echo "$CLAUDE_PLUGIN_ROOT"` y usar ese valor; (2) en cualquier otro cliente, o si la variable está vacía, la carpeta desde la que se cargó este archivo, dos niveles arriba. El destino de cada enlace markdown (`../../reference/…`) existe solo para navegar el repositorio en GitHub o en un editor: **no** resolverlo desde el directorio de trabajo. **Nunca buscar `reference/` en el proyecto**: un `<proyecto>/reference/language.md` que no existe no es un archivo que falte, es una ruta mal resuelta — corregir la raíz y volver a leer, sin preguntar al usuario ni saltarse la lectura.4950## Resolución de idioma5152Antes de ejecutar este skill, DEBES leer [`${PLUGIN_ROOT}/reference/language.md`](../../reference/language.md).5354Las reglas de `language.md` son obligatorias y tienen prioridad para determinar el idioma de todos los artefactos y mensajes generados por este skill.5556No continúes hasta haber leído y aplicado `language.md`.5758**Excepción deliberada:** los nombres de campos, rutas y payloads **no** siguen el idioma resuelto — siguen la convención del código existente (ver [`references/element-standards.md`](references/element-standards.md)).5960---6162## Ubicación de archivos6364Layout completo del harness e identificadores: [`${PLUGIN_ROOT}/reference/artifacts.md`](../../reference/artifacts.md).6566Lo propio de este skill:6768| Artefacto | Ruta |69| --------- | ---- |70| Documento técnico de capability (**salida**) | `docs/specs/technical-docs/[capability].md` |71| Archivos de apoyo (imágenes, esquemas exportados) | `docs/specs/technical-docs/assets/[capability]/` |72| Glosario (opcional) | `docs/specs/glossary.md` |7374### Convenciones7576- **Un documento por capability.** Si el documento de la capability ya existe, se **actualiza** (se añaden o modifican elementos); nunca crear un segundo documento para la misma capability.77- Nombre de archivo: capability en minúsculas, kebab-case, sin artículos ni palabras vacías. Ejemplos: `facturacion.md`, `gestion-recetas.md`, `autenticacion.md`.78- Dentro del documento, cada elemento lleva id secuencial **por tipo**, único en el ámbito de la capability: modelos `MD-01, MD-02, …`; APIs `API-01, API-02, …`; flujos `FL-01, FL-02, …`; diagramas `DG-01, DG-02, …`. No renumerar elementos existentes: los ids son estables porque otras historias y tareas ya pueden enlazarlos.79- Cada elemento es un encabezado `###` con el formato `### MD-01: Nombre`, precedido de su **ancla explícita** `<a id="md-01"></a>` en la línea inmediatamente anterior. La referencia que se cita es esa: `docs/specs/technical-docs/facturacion.md#md-01` — **el id en minúsculas, sin el nombre**. Nunca un ancla derivada del título (`#md-01-factura`): depende del renderizador y se rompe al renombrar el elemento. Ver [Por qué el ancla no se deriva del título](references/element-standards.md#por-qué-el-ancla-no-se-deriva-del-título).80- El documento lleva **fecha de creación** y **última actualización**. Las lagunas abiertas se registran en **Observaciones** del propio documento.8182---8384## Modos de invocación8586| Modo | Quién invoca | Entrada típica | Salida esperada |87| ---- | ------------ | -------------- | --------------- |88| **Directo** | El usuario | «Documenta el modelo de factura», «especifica la API de pagos», «dame más detalle del flujo de aprobación de la TK-004» | Documento creado/actualizado + resumen al usuario + oferta de enlazarlo desde la US/TK/WI relacionada |89| **Delegado** | `work-define` o `work-plan` vía subagente | Contexto de la US/TK/WI + los elementos técnicos a especificar | Documento creado/actualizado y, **como respuesta final del subagente, la lista de referencias** (ruta relativa + ancla `#<id>` de cada elemento) para que el skill llamador las agregue a la sección Referencias del artefacto |9091En modo delegado, el grilling de preguntas se dirige igualmente al usuario (el subagente hereda la herramienta de preguntas estructuradas); si el entorno no permite preguntar, documentar las lagunas en Observaciones y reportarlas en la respuesta final en lugar de inventar. **En modo directo**, si el entorno tampoco permite preguntar (p. ej. sesión desatendida/programada sin nadie que responda en el momento), aplicar el mismo criterio: no inventar, documentar cada laguna en Observaciones citando el elemento afectado, y destacarlas de forma prominente al principio del resumen final — a diferencia del modo delegado, aquí no hay un skill llamador que las recoja, así que es el propio resumen al usuario el único lugar donde quedan visibles.9293---9495## Cómo preguntar al usuario (grilling)9697Mecanismo, ritmo y fallback compartidos: [`${PLUGIN_ROOT}/reference/asking.md`](../../reference/asking.md).9899Cada vez que este skill o sus referencias digan *preguntar*, *pedir*, *confirmar*, *validar* o *sugerir* algo al usuario, asume ese mecanismo; no se repite allí.100101**Recopilación inicial (antes de redactar):** si hay más de tres lagunas, encadenar tandas hasta agotarlas o hasta que el usuario indique que lo restante quede como Observación.102103**No repreguntar** lo que ya está respondido en la US/TK/WI de origen o en el documento técnico existente.104105El detalle de **qué preguntar por tipo de elemento** (campos sin tipo, códigos de error sin definir, ramas de flujo ambiguas…) está en [`references/flow.md`](references/flow.md#grilling-por-tipo-de-elemento).106107---108109## Información requerida antes de redactar110111**No inventar nada** — si un dato no es explícito ni inferible del repo, preguntar al usuario (o reportarlo como laguna, en cualquier modo, cuando el entorno no permite preguntar — ver [Modos de invocación](#modos-de-invocación)).112113| Dato | Cómo obtenerlo | Si no está disponible |114| ---- | -------------- | --------------------- |115| **Capability** a la que pertenece el elemento | Indicada por el usuario/skill llamador, o inferible de la US/TK/WI y de los documentos existentes en `technical-docs/` | Preguntar; proponer opciones a partir de los documentos existentes antes de crear una capability nueva |116| **Tipo(s) de elemento** (modelo, API, flujo, diagrama) | Del pedido o del contenido de la US/TK/WI | Preguntar |117| **Contenido de cada elemento** (campos, contratos, pasos) | Del input recibido, del código existente del repo, o de la US/TK/WI de origen | Grilling de preguntas; lo irresoluble queda en Observaciones |118| **Artefacto(s) que lo consumirán** (US/TK/WI) | Del contexto o del skill llamador | Opcional en modo directo; si existe, ofrecer enlazar la referencia al terminar |119120---121122## Flujo (resumen)123124El procedimiento completo está en [`references/flow.md`](references/flow.md). Síntesis:125126- **Crear/actualizar:** resolver capability → leer el documento existente si lo hay → detectar lagunas y hacer el grilling → redactar los elementos con `assets/technical-doc-template.md` y los estándares de `references/element-standards.md` → asignar ids estables → actualizar la fecha de última actualización → glosario si aplica.127- **Enlazar:** en modo delegado, devolver las referencias (ruta + ancla `#<id>`) al skill llamador; en modo directo, ofrecer agregar la referencia a la sección Referencias de la US/TK/WI relacionada.128- **Cierre:** si quedaron lagunas en Observaciones, ofrecerle al usuario las preguntas que las cerrarían (misma mecánica de grilling).129130---131132## Mensaje al usuario133134Solo resultados y lo que el usuario debe saber o decidir. No incluir razonamiento interno ni narración del trabajo en curso («leí la US», «creé el archivo»). Si hay pendientes, listarlos agrupados por elemento (`MD-XX`, `API-XX`, `FL-XX`, `DG-XX`). En modo delegado, la respuesta final del subagente es **datos para el skill llamador** (rutas y anclas `#<id>`), no prosa para el humano.
juanca202