Este archivo está destinado a consumidores de la habilidad, no a contribuidores. Consulte AGENTS.md para el contexto de desarrollo: cómo se construye, itera y prueba esta habilidad.
Inicio del Espacio de Trabajo de Documentación
Esta habilidad enseña a un agente de IA cómo iniciar un espacio de trabajo de documentación desde cero en un directorio vacío (o casi vacío). El resultado es una base de conocimiento versionada, basada en sistema de archivos y completamente autocontenida, propiedad del usuario, gratuita, sin dependencia de proveedor y estructurada para que el agente que trabaja en ella nunca tenga que pensar en organización, formato o herramientas.
La idea central
Un espacio de trabajo iniciado contiene su propio AGENTS.md, un "mini-skill" congelado y específico del tema que el agente lee al entrar. AGENTS.md se crea a partir de una plantilla que incluye esta habilidad. Una vez que el espacio de trabajo existe, el agente sigue AGENTS.md, no esta habilidad. Ese es el punto clave: decidir las reglas una vez y luego no quemar tokens volviéndolas a derivar.
Cuándo usar esta habilidad
Use esta habilidad solo cuando:
- El usuario quiere explícitamente crear / configurar / inicializar / andamiar un espacio de trabajo de documentación, una carpeta de documentación o una base de conocimiento.
- El directorio de destino está vacío o casi vacío (o el usuario ha optado explícitamente a pesar de los archivos existentes).
- El directorio de destino no contiene ya un
AGENTS.md(lo que significaría que ya está iniciado).
Si AGENTS.md ya existe en el destino: no ejecute esta habilidad. Lea el AGENTS.md existente y sígalo. El usuario ya está en un espacio de trabajo iniciado.
Cuándo NO usar esta habilidad
- El usuario quiere agregar un documento, editarlo, enlazar documentos o reorganizar dentro de un espacio de trabajo existente; el
AGENTS.mddel espacio de trabajo gobierna eso. - El usuario quiere enviar a GitHub, renderizar el espacio de trabajo en un navegador o configurar alojamiento: son preocupaciones diferentes, habilidades diferentes.
- El usuario está haciendo una pregunta genérica sobre documentación, escritura o toma de notas: no se necesita habilidad.
Lo que produce la habilidad
Cuando se invoca, esta habilidad crea un espacio de trabajo que contiene:
| Archivo / Directorio | Propósito |
|---|---|
AGENTS.md | El "mini-skill congelado" del espacio de trabajo. 95% reglas, 5% resumen del tema. El agente lo lee al entrar. |
README.md | Resumen general del espacio de trabajo. Introducción más rica, índice autogenerado, enlace a AGENTS.md. |
index.yaml | Orden de documentos para el directorio raíz. Vacío por defecto. |
.gitignore | Valores predeterminados sensatos: copias de seguridad, basura del SO, archivos del editor, Node. |
package.json | Dependencias de desarrollo: prettier, markdownlint-cli, js-yaml. Scripts npm para herramientas. |
.prettierrc | Configuración de Prettier: línea de 120 caracteres, proseWrap preserve. |
.markdownlint.json | Configuración de markdownlint con reglas de nitpicking desactivadas. |
scripts/ | Scripts auxiliares: format.js, validate.js, hash.js, reindex.js. |
assets/ | Directorio vacío de recursos compartidos. Creado en la raíz del espacio de trabajo. |
Se inicializa un repositorio Git en el espacio de trabajo si git está disponible. Las dependencias de desarrollo se instalan si Node y npm están disponibles.
Flujo de trabajo de inicio
Siga estos pasos en orden. Confirme con el usuario en cada paso donde se indique. Nunca asuma.
Paso 1 — Confirmar ubicación de destino
Pregunte al usuario: "Iniciaré el espacio de trabajo de documentación en <cwd>. ¿Es correcto? (sí / no / especifique una ruta)"
- Si
sí: continúe con cwd como destino. - Si
no: solicite la ruta correcta, confirme y luego continúe. - Si el usuario dijo "en esta carpeta" o similar: asuma cwd, pero confirme de todos modos.
Paso 2 — Confirmar que el destino está vacío (u obtener aceptación)
Enumere el contenido del directorio de destino (excluyendo archivos ocultos como .git).
Si está vacío: continúe al Paso 3.
Si no está vacío:
- Muestre al usuario lo que hay.
- Explique: "Este directorio no está vacío. Por defecto, esta habilidad se niega a iniciar en un directorio no vacío. Puedo (a) abortar, (b) si confirma que quiere continuar de todos modos, dejaré los archivos existentes intactos, o (c) especificar un subdirectorio para crear el espacio de trabajo."
- Espere confirmación explícita. Si el usuario no da una afirmación positiva estricta, aborte.
- Si el usuario dice "adelante" o "sí, continúa" — regístrelo como aceptación y continúe.
Si AGENTS.md ya existe en el destino: deténgase. El espacio de trabajo ya está iniciado. Dígaselo al usuario y ofrezca leer el AGENTS.md existente.
Si git ya está inicializado en el destino: omita el paso de git init más tarde, pero continúe.
Paso 3 — Recopilar el resumen del tema
Pregunte al usuario: "¿Para qué es este espacio de trabajo de documentación? Describa el tema en 1 o 2 párrafos cortos. Esto se convierte en el resumen del tema en AGENTS.md y la introducción en README.md."
Reglas del resumen del tema:
- 1 párrafo (preferido), máximo 2 párrafos
- Prosa simple, sin formato, sin listas
- Declaración clara de lo que documenta el espacio de trabajo
Si el usuario da una sola oración: está bien, úsela. Si el usuario da una descripción más larga: condénsela (con su confirmación) o use un máximo de 2 párrafos. Si el usuario dice "tú decides" o "aún no lo sé": solicite al menos una oración; el resumen del tema es la única parte específica del tema en AGENTS.md, y el espacio de trabajo necesita algún ancla.
Paso 4 — Ejecutar el script de inicio
Una vez que tenga:
- La ruta de destino
- Confirmación de que el directorio es apropiado
- El resumen del tema
...ejecute el script de inicio:
node /assets/skill-scripts/bootstrap.js --target --topic ""
El script:
- Verificará la disponibilidad de Node.js (omitirá artefactos dependientes de Node y advertirá si no está)
- Verificará la disponibilidad de git (omitirá
git initsi no está) - Creará la estructura de directorios
- Instanciará todas las plantillas de
<skill-dir>/assets/templates/con{{TOPIC_SUMMARY}}y{{CREATED}}sustituidos - Copiará los scripts incluidos en el espacio de trabajo (
format.js,validate.js,hash.js,reindex.js) a<target>/scripts/ - Ejecutará
npm install(si Node + npm están disponibles) - Ejecutará
git init(si git está disponible) - Imprimirá un resumen de lo que se creó
Si el script falla (por ejemplo, permisos, herramienta faltante), recurra a la creación manual de archivos usando las plantillas en <skill-dir>/assets/templates/. Copie manualmente cada plantilla al destino, sustituya los marcadores de posición y cree el directorio de scripts copiando desde <skill-dir>/assets/workspace-scripts/.
Paso 5 — Informar al usuario lo que se creó
Después de que el script termine, resuma:
- Qué archivos y directorios se crearon
- Si se ejecutó
git init(o se omitió, con un recordatorio) - Si se ejecutó
npm install(o se omitió, con un recordatorio) - Que
AGENTS.mdes ahora el documento rector de este espacio de trabajo - Que el espacio de trabajo está listo para usar
Luego pregunte: "¿Quiere comenzar a trabajar en la documentación o desea revisar la estructura primero?"
Plantillas
Todos los archivos de plantilla viven en <skill-dir>/assets/templates/. El script de inicio los copia y sustituye.
| Plantilla | Produce |
|---|---|
AGENTS.md.template | AGENTS.md |
README.md.template | README.md |
index.yaml.template | index.yaml |
_gitignore_.template | .gitignore (envuelto con guión bajo se convierte en prefijo de punto) |
package.json.template | package.json |
_prettierrc_.template | .prettierrc |
_markdownlint.json_.template | .markdownlint.json |
Marcadores de posición usados:
{{TOPIC_SUMMARY}}— reemplazado con la descripción del tema del usuario{{CREATED}}— reemplazado con la fecha de hoy (AAAA-MM-DD)
El script de inicio maneja la convención de envoltura con guión bajo automáticamente (un archivo llamado _foo_.template se convierte en .foo en la salida).
Scripts incluidos en el espacio de trabajo
Después del inicio, el espacio de trabajo tiene estos scripts auxiliares en scripts/:
| Script | Propósito |
|---|---|
scripts/format.js | Ejecuta Prettier en todos los archivos .md/.html/.json/.yaml |
scripts/validate.js | Ejecuta markdownlint en todos los archivos .md |
scripts/hash.js | Calcula el hash SHA-256 de un archivo, opcionalmente lo escribe en assets/ y actualiza el manifiesto |
scripts/reindex.js | Regenera la sección de índice automático en README.md |
Todos son invocables mediante npm:
npm run formatnpm run validatenpm run hashnpm run reindex
Referencias
Para un contexto más profundo sobre temas específicos, consulte el directorio references/:
references/asset-management.md— Cómo agregar, enlazar y migrar recursos (almacenamiento direccionado por contenido, manifiesto, por documento vs compartido)references/document-promotion.md— Cómo promover un documento de un solo archivo a una carpeta cuando gana subdocumentos
Estos se cargan en el contexto solo cuando son relevantes. El AGENTS.md principal cubre los casos comunes; las referencias son para los menos comunes.
Recordatorios para el agente (durante el inicio)
- El resumen del tema es el único contenido específico del tema que proporciona el usuario. Todo lo demás está en plantillas. No pregunte sobre nombres de archivos, estilos de enlaces, campos de frontmatter, estilo de mensajes de confirmación ni ninguna otra regla; esos están integrados en las plantillas.
- Si el usuario solicita algo que las plantillas no admiten, menciónelo. No invente nuevas convenciones en silencio. Lo correcto es (a) anotarlo para una futura revisión de la plantilla, o (b) implementarlo como una excepción con confirmación explícita.
- Después del inicio, esta habilidad ha terminado. La próxima vez que el usuario quiera hacer algo en el espacio de trabajo, el agente lee
AGENTS.mdy lo sigue. Esta habilidad no se ejecuta de nuevo a menos que el usuario solicite explícitamente iniciar otro espacio de trabajo o reiniciar el existente.