wiki-smith

wiki-smith — mantén el .wiki/ del repositorio

Un wiki es la memoria del repositorio, escrita para agentes: aquí encuentran la regla en lugar de volver a preguntar. El diario contiene lo que sucedió; la página temática contiene lo que es válido ahora. Una lección que solo vive en el diario está perdida. wiki-smith decide cuál de los dos necesita una sesión, lo escribe según las reglas del propio wiki y lo verifica.

Método completo (tipos de archivo, formato de nota, ingesta, enlaces, fechas, commit): references/method.md. Claves de configuración: references/config.md. Créditos: ATTRIBUTION.md. Cambios: CHANGELOG.md. Su propia memoria: .wiki/.

<skill> a continuación es la carpeta de esta skill (por ejemplo ~/.claude/skills/wiki-smith). Cada script acepta -w <directorio wiki> (por defecto ./.wiki) y -c <config> (por defecto <wiki>/wiki.config).

Paso 0 — Encuentra el wiki y sus reglas

1. El wiki es .wiki/ en la raíz del repositorio. Si no existe, indícalo y ofrece crear uno a partir de templates/ (wiki.config.example primero); nunca lo crees sin que se te pida.
2. Lee .wiki/wiki.config si existe (nombres: carpeta del diario, bandeja de entrada, índice, etiqueta de pie de página, claves de fecha, rama principal). Sin él, los valores predeterminados son inglés genérico: journal/, inbox.md, index.md, Map:, ## History, created/updated.
3. Las reglas del propio wiki prevalecen. Si el repositorio tiene una página sobre cómo mantenerlo (rg -n -i 'mantener|manter' .wiki -l) o una regla AGENTS.md sobre el wiki, lee esa sección y síguela donde difiera de esta skill.
4. Si el usuario solicitó "actualizar el wiki" y el wiki (generalmente el índice) dice que hay que confirmar primero, haz el Paso 1 y el Paso 2 solo como plan: una línea por página con los cambios, los títulos de las nuevas notas, luego pregunta "¿Aplicar?" y edita solo después de un sí. De lo contrario, actúa.

Paso 1 — Revisa lo que pasó, luego decide

Lee la sesión (y git diff, git log para el trabajo realizado). Elige cada fila que aplique, y nada más:

Qué tuvo la sesión	Qué hacer
Una decisión, entrega, cambio de rumbo, incidente o investigación	Una nota diaria: scripts/note.sh -b "Título que indique qué cambió" con el párrafo canalizado. Luego, la línea del día en la bandeja de entrada.
Una regla, lección o hecho que sea válido más allá de hoy	También corrige la página temática: la regla tal como es válida ahora, sin historia (la historia se queda en la nota y en la sección de Historial de la página). Corrige lo que decía antes la página; nunca acumules "antes era".
Un tema nuevo con varias facetas (volverá a aparecer, y una sola página mezclaría tipos)	Un mapa de contenido moc-<tema>.md más las páginas <tema>-<faceta>.md (chuleta, instalación, integración, comparación con la herramienta actual...). Ver "Tema nuevo" más abajo.
Nada digno de registrar (solo pasos intermedios, o lo que un commit ya dice)	Dilo en una línea y no crees nada. Engordar el diario lo hace ilegible.

Solo se crea una nota nueva para el diario; nunca se reescribe la nota de otro agente.

Paso 2 — Escribe

Nota diaria. scripts/note.sh "<título>" crea <DIARIO_DIR>/<hoy>/<HHMM>-<slug>.md en UTC e imprime la ruta (reglas de slug y -2 en caso de colisión están en el script). Stdin se lee solo con -b: los shells de agente y CI dejan stdin abierto para siempre, por lo que sin -b el script nunca espera. Canaliza el cuerpo: printf '%s\n' "<párrafo>" | scripts/note.sh -b "<título>"; -b pone exactamente una línea en blanco entre el título y el cuerpo. Sin -b el archivo solo tiene la línea del título; para añadir el párrafo después, empieza con una línea en blanco: printf '\n%s\n' "<párrafo>" >> "$ruta". El cuerpo es un párrafo bien redactado: qué pasó, por qué importa, dónde está la evidencia (commit, PR, issue), con un enlace a la página temática. Los enlaces son relativos a la carpeta del día (../../pagina.md). Plantilla: templates/note.md.

Primera nota del día: scripts/day-index.sh crea el índice del día; luego añade el día al principio de "últimos días" en la bandeja de entrada. Si la nota cambia el funcionamiento del repositorio, añade también una línea a los destacados de la bandeja de entrada. La bandeja de entrada nunca contiene una nota.

Página temática (ingesta). Encuéntrala (rg -n -i '<palabra>' .wiki); si no existe y el tema volverá, créala (plantilla: templates/page.md); si es pequeño, ponlo en una sección de una página cercana. Escribe la regla tal como es válida ahora. Si un cambio altera lo que la página afirma, añade una línea al principio de su sección de Historial. La nota enlaza a la página.

Tema nuevo.

1. Escribe primero las páginas, una por faceta, cada una autocontenida desde la primera frase. Facetas típicas: chuleta (la primera: direcciones, comandos, atajos), instalación, integración, comparación con la herramienta en uso actual.
2. Crea moc-<tema>.md (templates/moc.md): un párrafo de apertura, "las páginas" (una línea cada una, chuleta primero), "qué saber primero" (las pocas reglas que afectan).
3. Dale a cada página el pie de página (Map: [moc-<tema>](moc-<tema>.md) · Relacionado: ...), añade el mapa y cada página al índice, y enlaza el mapa desde al menos otro mapa.
4. Una nota en el diario dice qué se creó y enlaza el mapa.

Paso 3 — Cierre (siempre, en este orden)

1. scripts/dates.sh — el frontmatter created/updated, desde git. Idempotente.
2. scripts/day-index.sh — regenera el índice diario. Nunca lo edites a mano.
3. python3 -I scripts/lint.py — corrige cada archivo:línea: tipo: mensaje que imprima hasta que salga con 0 (salida 2 significa problemas). No entregues un lint rojo.
4. Confirma solo tus propios archivos, por ruta, nunca git add -A: scripts/sync.sh -m "wiki: <qué>" <ruta>.... Confirma en el lugar cuando el checkout está en <main>, actual y sin cambios fuera de tus rutas; de lo contrario, lleva tus rutas a un git worktree nuevo desde origin/<main>. En cualquier caso, aplica lint exactamente a lo que confirma y rechaza un lint rojo (salida 1, checkout intacto, worktree eliminado). En el traslado, el índice diario generado nunca se copia: se regenera en el worktree, por lo que solo lista las notas que están en el commit. Añade las líneas de atribución que el repositorio o tu anfitrión requieran al mensaje.
   • Archivos compartidos (índice, bandeja) que otra sesión puede haber editado también: no los pases a un traslado. scripts/sync.sh -W imprime un worktree nuevo desde origin/<main>; haz tus ediciones allí (el wiki está en la misma ruta relativa), ejecuta dates.sh, day-index.sh, lint.py, luego ejecuta sync.sh -m ... [-p] <rutas> desde dentro de ese worktree. Confirma allí, y con -p rebasea, empuja, avanza rápido el checkout principal donde pueda, y elimina el worktree. Un traslado que incluya líneas de otra sesión (por ejemplo, un enlace a una página que solo está en el checkout) falla el lint y se detiene antes de confirmar; ese fallo es la señal para usar -W.
5. Empuja solo cuando el usuario pidió sincronizar: la misma llamada con -p (fetch, rebase, push HEAD:<main>, avance rápido del checkout, elimina el worktree). Nunca fuerces, nunca toques archivos modificados por otros: un archivo que difiere de lo que empujaste y puede contener ediciones de otra sesión (índice, bandeja) se deja como está. Si el checkout no puede avanzar rápido (<main> local divergió, o ediciones locales superpuestas) lo indica y aún así sale con 0, porque el push funcionó. Abre un PR solo cuando te lo pidan.

Confirma lo que escribiste en la misma sesión sin esperar a que te lo pidan; publicar es decisión del usuario.

Consultar el wiki

rg -n -i '<palabra clave>' .wiki (o hojea el índice), luego lee solo la página o sección que coincida, nunca todo el wiki. Para lo que ocurrió: la bandeja de entrada (breve), luego solo los días que importen; un día = su índice y las notas que lista. Si el repositorio tiene especificaciones, estas dicen lo que el sistema promete: rg -n -i '<palabra clave>' <directorio de especificaciones>.

Errores comunes

• El diario no es la página. Una regla escrita solo en una nota se pierde; intégrala en la página temática en la misma sesión.
• Reglas sin historia. "Antes de crear una tarjeta, busca las existentes", no "solíamos duplicar tarjetas". La historia se queda en la nota.
• Una nota por archivo. Varios agentes escriben el mismo día; nunca deben editar el mismo archivo. El índice diario se genera; los conflictos allí se resuelven ejecutando day-index.sh de nuevo.
• Archivos compartidos entre sesiones. El índice diario, index.md y la bandeja de entrada contienen todas las ediciones no confirmadas de todas las sesiones en un solo checkout. sync.sh nunca lleva el índice diario (lo regenera en el worktree) y aplica lint antes de confirmar, pero no puede saber qué partes de un index.md o bandeja editados a mano son tuyas: el traslado toma todo el diff. Cuando otra sesión pueda haberlos tocado, usa sync.sh -W y edita en el worktree. Una línea extraña que casualmente no rompa el lint igual se lleva; ese es el límite documentado del traslado.
• Nunca esperes en stdin. note.sh lee el cuerpo solo con -b; en un shell de agente, una lectura simple bloquea para siempre. Lo mismo aplica a cualquier script que añadas.
• No registres lo transitorio: un comando que falló una vez y funcionó al reintentar, un fallo de entorno, una tarea puntual. Captura la solución funcional en la página temática, nunca "X está roto" (se endurece como un rechazo después de que la causa desaparezca).
• Enlaces: relativos, solo la primera mención por sección; un ancla es el slug de GitHub del encabezado (minúsculas, sin puntuación, acentos conservados, espacio se convierte en guión). Renombrar un encabezado rompe sus anclas; el lint lo indica. Pon un ejemplo de enlace dentro de comillas invertidas para que el lint no lo lea.
• Renombrar o eliminar una página: rg -l 'nombre-antiguo' .wiki y corrige todos los enlaces, incluidas las anclas; elimina solo después de que el contenido se haya movido.
• Tamaño de página: Pasadas unas 150 líneas, o cuando la regla, el procedimiento, la referencia y la historia se mezclan, divide por tipo.
• Los datos privados se quedan fuera. Las páginas del wiki se confirman; mantén fuera secretos, tokens y datos personales, y referencia dónde vive el secreto en su lugar.
• Límites del lint: no detecta contradicciones entre páginas ni afirmaciones obsoletas; eso es una revisión del agente cuando el tiempo lo permita.
• Límite de day-index.sh: un archivo de día con notas escritas a mano en formato antiguo es un error (archivo:línea), no se migra; mueve cada nota a su propio archivo con note.sh, vuelve a ejecutar.

Paso 4 — Mantén tu propio wiki

Si esta ejecución enseñó algo sobre la ejecución de wiki-smith (un error de enrutamiento, una peculiaridad del script), añade una línea a .wiki/lessons.md: - YYYY-MM-DD — <regla + por qué>. Edita el clon fuente (biliboss/wiki-smith) y reinstala (npx skills add biliboss/wiki-smith -g --copy -a claude-code -y), no la copia instalada, que una reinstalación sobrescribe. Las decisiones de diseño van en .wiki/design.md.