Teardown gstack: qué habilidades pueden aprender los desarrolladores

Introducción

En Concepto y Práctico, aprendimos qué es gstack y cómo usarlo desde la perspectiva del usuario. Esta nota es desde una perspectiva diferente: ** Como desarrollador de habilidades **, después de leer el archivo del almacén gstack, qué diseños de ingeniería vale la pena aprender y aprender.

gstack es más que una simple colección de 23 archivos de mensajes. Hay un sistema de ingeniería completo detrás: generación de plantillas, actualización automática, aprendizaje y memoria, guía progresiva, adaptación multiplataforma, pruebas en capas: estas son las claves para convertir un proyecto de habilidades de "utilizable" a "fácil de usar".

1. SKILL.md no está escrito a mano: sistema de generación de plantillas

El diseño más contrario a la intuición de gstack: **Cada SKILL.md se genera automáticamente y no se puede editar directamente. **

SKILL.md.tmpl (人写)  →  gen-skill-docs  →  SKILL.md (机生)

La plantilla .tmpl escrita por humanos contiene lógica de flujo de trabajo y mejores prácticas, además de marcadores de posición {{PLACEHOLDER}}. El script de compilación extrae la referencia del comando, la lista de indicadores del navegador, el código de inicio del preámbulo, etc. del código fuente y los completa en los marcadores de posición para generar el SKILL.md final.

{{PREAMBLE}}           ← 从 resolvers/preamble.ts 生成的启动代码
{{BROWSE_SETUP}}       ← 浏览器初始化指令
{{COMMAND_REFERENCE}}  ← 从 commands.ts 提取的命令文档
{{SNAPSHOT_FLAGS}}     ← 从源代码常量提取的快照选项

**¿Por qué hacer esto? **

• La documentación y el código nunca estarán desincronizados: la referencia del comando se genera a partir del código fuente y la documentación se actualiza automáticamente cuando cambia el código fuente.
• 23 habilidades comparten el mismo preámbulo (alrededor de 220 líneas) y todas las habilidades se actualizan simultáneamente
• CI puede --dry-run comprobar si el archivo generado ha caducado para evitar olvidarse de regenerar

Conclusión: Si mantiene varias habilidades, cualquier contenido compartido entre habilidades debe extraerse en plantillas y usarse en los pasos de compilación para generar los archivos finales. Sincronizar manualmente varias copias del mismo contenido causará problemas tarde o temprano.

2. Mecanismo de actualización: enlace completo desde la detección hasta la ejecución

El sistema de actualización de gstack está exquisitamente diseñado y dividido en tres capas:

Primera capa: detección de versión

bin/gstack-update-check es un script bash independiente que hace lo siguiente:

1. Lea el archivo VERSION local
2. Verifique el caché ~/.gstack/last-update-check (cachés UP_TO_DATE durante 60 minutos, cachés UPGRADE_AVAILABLE durante 720 minutos)
3. Si el caché caduca, solicite HTTP raw.githubusercontent.com/.../VERSION de GitHub.
4. Compare el número de versión y genere UPGRADE_AVAILABLE <旧> <新>

Segunda capa: integración del preámbulo

La primera línea del código de inicio de SKILL.md de cada habilidad es la detección de versión:

_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true

Esto significa que las actualizaciones se detectarán automáticamente cuando los usuarios llamen a cualquier habilidad; no es necesario ejecutar un comando de actualización específicamente, presencia cero pero cobertura del 100 %.

El tercer nivel: recordatorio progresivo + actualización automática

Después de detectar una nueva versión, no molestará inmediatamente al usuario, sino que utilizará el mecanismo de repetición (Snooze) para un retroceso progresivo:

• Primer recordatorio: vuelva a mencionarlo después de 24 horas
• Segundo recordatorio: mencione nuevamente después de 48 horas
• Tercera vez y después: mencione nuevamente después de 7 días
• El lanzamiento de la nueva versión restablece el contador de repetición

Los usuarios pueden gstack-config set auto_upgrade true habilitar la actualización automática y omitir la confirmación para ejecutarla directamente.

Al realizar la actualización se distinguirán 5 tipos de instalación (git global, git local, suministrada, etc.). La instalación de git utiliza git fetch + reset, la instalación proporcionada primero realiza una copia de seguridad y luego reemplaza y restaura desde .bak en caso de falla. Después de la actualización, la copia del proyecto suministrada localmente también se sincronizará automáticamente.

Puntos de los que vale la pena aprender:

• El modo "detectar en cada llamada" tiene una cobertura extremadamente alta y es imperceptible para los usuarios
• El retroceso gradual evita interrupciones frecuentes
• Diferenciar los tipos de instalación e implementar diferentes estrategias de actualización en lugar de una solución única para todos
• La copia de seguridad y la restauración garantizan que una falla en la actualización no provoque que se cuelgue toda la habilidad.

3. Sistema de aprendizaje: haga que las habilidades sean más inteligentes cuanto más las use

gstack implementa un sistema de memoria de sesiones cruzadas liviano pero efectivo.

Almacenamiento

Cada proyecto tiene un registro de aprendizaje independiente: ~/.gstack/projects/$SLUG/learnings.jsonl, que se escribe adicionalmente.

{
  "skill": "review",
  "type": "pitfall",
  "key": "n-plus-one",
  "insight": "这个项目的 User model 有 N+1 查询问题，findAll 要加 include",
  "confidence": 8,
  "source": "observed",
  "files": ["src/models/user.ts"],
  "ts": "2026-04-01T14:30:00Z"
}

Colección automática

Antes de completar cada habilidad, hay un enlace de "mejora personal operativa", que refleja si se descubrieron fallas inesperadas, desvíos o peculiaridades del proyecto durante la ejecución, y cualquiera se registrará automáticamente en learnings.jsonl. El usuario no requiere activación manual.

Carga automática

Cada vez que comienza una nueva sesión, el preámbulo cargará las primeras 3 entradas de aprendizaje de alta confianza para inyectar contexto, permitiendo que la nueva sesión herede el conocimiento histórico.

Caída de la confianza

Las entradas de fuentes observed y inferred decaen 1 punto cada 30 días. No es necesario limpiar manualmente la base de conocimientos: los conocimientos obsoletos se desvanecen de forma natural y nuevas observaciones ocupan su lugar de forma natural.

Interfaz de gestión

/learn            # 显示最近 20 条
/learn search     # 搜索
/learn prune      # 检测过期条目（引用的文件已删除）
/learn export     # 导出为 markdown 可加入 CLAUDE.md

Puntos de los que vale la pena aprender:

• El diseño adicional de solo escritura es simple y confiable, y la concurrencia es segura
• La pérdida de confianza es una gestión del envejecimiento del conocimiento que requiere poco mantenimiento y es mucho más eficiente que la limpieza manual.
• Utilice la URL remota de git en lugar de la ruta para identificar el proyecto (a través de gstack-slug), que se puede clonar en diferentes ubicaciones y reutilizar.
• Admite consultas entre proyectos, pero está aislado de forma predeterminada.

4. Inyección de preámbulo: "capa de middleware" de la habilidad

Este es uno de los diseños arquitectónicos más inteligentes de gstack. Cada SKILL.md comparte un código de preámbulo de aproximadamente 220 líneas, que funciona como el middleware de un marco web:

┌─ 更新检测 ──────────────────────────────────┐
│ 会话追踪 (sessions/$PPID)                    │
│ 配置读取 (proactive, skill_prefix, telemetry)│
│ 学习历史加载 (前 3 条高置信度)                │
│ 上下文恢复 (最近的 checkpoint + timeline)     │
│ 路由规则检测                                 │
│ 首次使用引导流程                              │
└──────────────────────────────────────────────┘
         ↓
    Skill 特有逻辑

El script bash de Preamble genera pares clave-valor (BRANCH: main, PROACTIVE: true), y luego la plantilla usa condiciones de lenguaje natural para permitir que Claude ajuste su comportamiento en consecuencia:

If PROACTIVE is false, do not invoke skills automatically.
Instead suggest: "I think /skillname might help here -- want me to run it?"

Básicamente, se trata de tratar la salida de bash como las "variables de entorno" de Claude: utilizar bash para la detección del tiempo de ejecución y el lenguaje natural para el enrutamiento del comportamiento.

Puntos de los que vale la pena aprender: si tiene varias habilidades, la lógica compartida (carga de configuración, recuperación de estado, detección de versión) debe extraerse en un preámbulo unificado en lugar de escribir una copia para cada habilidad.

5. Arranque progresivo: modo de archivo Sentinel

La experiencia del usuario primerizo de gstack está diseñada con mucho cuidado. Asegúrese de que cada paso de inicio ocurra solo una vez mediante un archivo táctil (archivo centinela):

~/.gstack/.completeness-intro-seen    ← "Boil the Lake" 理念介绍
~/.gstack/.telemetry-prompted         ← 遥测选择（community/anonymous/off）
~/.gstack/.proactive-prompted         ← 主动触发开关
~/.gstack/.routing-prompted           ← CLAUDE.md 路由规则写入
~/.gstack/.welcome-seen               ← 安装欢迎消息

Compruebe si estos archivos existen cada vez que se inicia la habilidad. De lo contrario, muestre los archivos táctiles y de inicio correspondientes. Los pasos que ya han sido vistos nunca volverán a aparecer.

Puntos de los que vale la pena aprender: en comparación con mantener el estado de "onboarding_step": 3 en la configuración, los archivos centinela son más simples y confiables: no se verán afectados por la corrupción del archivo de configuración y cada paso se controla de forma independiente.

6. Diseño estructural de SKILL.md: arquitectura de tres niveles

Cada SKILL.md sigue una estructura estándar de tres capas:

Primera capa: YAML Frontmatter

---
name: qa
preamble-tier: 3
version: 0.15.1.0
description: |
  Systematically QA test a web application...
  Use when asked to "qa", "test this site", "find bugs"...
benefits-from: [office-hours]
allowed-tools:
  - Bash
  - Read
  - Write
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "bash ${CLAUDE_SKILL_DIR}/bin/check-careful.sh"
---

Campos clave:

• allowed-tools: lista blanca de permisos a nivel de herramienta, cada habilidad declara solo las herramientas que necesita
• benefits-from: Declarar explícitamente la habilidad previa a la dependencia
• hooks: gancho PreToolUse, que puede interceptar antes de que se llame a la herramienta (como la intercepción cuidadosa rm -rf)
• description: contiene todas las palabras desencadenantes en lenguaje natural

Capa 2: Preámbulo compartido + Reglas generales

Código de inicio de preámbulo + Definición de voz + recuperación de contexto + principio de integridad + prioridad de búsqueda + protocolo de estado de finalización + reglas de actualización, etc. Todas las habilidades son idénticas y se generan a partir de plantillas.

La tercera capa: lógica específica de habilidades

Esta es el "alma" de cada habilidad: definición del flujo de trabajo, configuración de roles, inyección de modelos cognitivos, activación de interacciones, etc.

Puntos de los que vale la pena aprender: la separación de tres capas permite que cada habilidad se centre únicamente en su propia lógica única, y el marco garantiza las partes compartidas para mantener la coherencia.

7. Colección rápida de consejos de ingeniería

Después de leer todo SKILL.md, estas son las técnicas de diseño rápido que vale la pena aprender:

Reglas anti-adulación

El modo de inicio del horario de oficina prohíbe explícitamente el comportamiento común "y confuso" de la IA:

Never say:
- "That's an interesting approach" → take a position instead
- "There are many ways to think about this" → pick one
- "You might want to consider..." → say "This is wrong because..."
- "That could work" → say whether it WILL work

Lista de palabras prohibidas

La sección Voz tiene palabras y frases claramente prohibidas:

• Palabras prohibidas: profundizar, crucial, robusto, integral, matizado, fundamental, paisaje...
• Frases prohibidas: "aquí está el truco", "giro de la trama", "déjame desglosar esto"...
• Formato deshabilitado: em guión (reemplazar con coma/punto)

Estas son palabras comunes con "sabor a IA" en LLM, y el resultado es obviamente más natural después de desactivarlas.

Inyección de modelo cognitivo

Cada habilidad de revisión inyecta un marco de pensamiento diferente:

• Revisión del CEO: 18 modelos cognitivos (la toma de decisiones de puerta unidireccional y bidireccional de Bezos, el pensamiento inverso de Munger, el enfoque y la resta de Jobs...)
• Revisión en inglés: 15 patrones de gestión de ingeniería ("aburrido por defecto", intuición del radio de explosión, ley de Conway...)
• Revisión de diseño: 12 patrones de cognición de diseño (Jerarquía como servicio, Adoración de las restricciones, Pruebas "¿Me daría cuenta?"...)

Estos modos no permiten que la IA funcione mecánicamente, sino que le proporcionan un marco de pensamiento, como si le dieran a un recién llegado inteligente una lista de experiencias de sus predecesores.

Estándares de especificación

Not "you should test this"
    but `bun test test/billing.test.ts`

Not "this might be slow"
    but "this queries N+1, ~200ms per page load with 50 items"

Not "there's an issue in the auth flow"
    but "auth.ts:47, the token check returns undefined"

Calibración de confianza

La habilidad de revisión requiere que cada descubrimiento vaya acompañado de una puntuación de confianza, y los hallazgos de baja confianza se degradan u ocultan automáticamente:

Puerta interactiva

La habilidad del barco define con precisión cuándo detenerse y esperar al usuario y cuándo continuar automáticamente:

Only stop for:
- Tests failing with no obvious fix
- Merge conflicts requiring human judgment
- Unclear which changes to include

Never stop for:
- Normal git operations
- CHANGELOG/VERSION updates
- PR creation

Puntos de los que vale la pena aprender: una buena habilidad no es "la IA hace todo", sino una definición precisa de la frontera entre humanos y máquinas.

8. Gestión de estado: el sistema de archivos es una base de datos

Toda la persistencia de gstack se realiza a través del sistema de archivos, almacenado en ~/.gstack/:

Casi todos los datos de series temporales se escriben de forma anexa utilizando JSONL (un objeto JSON por fila). Esta elección es inteligente:

• Se agregó seguridad de concurrencia natural de escritura.
• No se requieren dependencias de bases de datos
• Puede utilizar grep / jq para realizar consultas directamente
• Corrupto hasta faltar la última línea.

9. Modo de integración entre habilidades

Producto de transferencia de archivos

Transferir productos de trabajo entre habilidades a través del sistema de archivos:

/office-hours → design doc → /plan-ceo-review 读取
/plan-ceo-review → ceo-plans/*.md → /autoplan 读取
/review → reviews.jsonl → /ship 读取并展示 Dashboard
/qa → qa-reports/ → /retro 读取

Review Readiness Dashboard

La habilidad del barco dice reviews.jsonl, lo que muestra el estado de revisión de habilidades cruzadas antes de publicar:

| Review          | Runs | Last Run    | Status | Required |
| Eng Review      |  1   | 2026-03-16  | CLEAR  | YES      |
| CEO Review      |  0   | —           | —      | no       |
| Design Review   |  0   | —           | —      | no       |

Sugerencias previas a la dependencia

Cuando plan-ceo-review detecta que no hay ningún documento de diseño, recomendará activamente ejecutar /office-hours primero:

"No design doc found. /office-hours produces a structured problem statement...
Takes about 10 minutes."
Options: A) Run /office-hours now  B) Skip

Usar predicción de secuencia

Context Recovery analizará la secuencia reciente de uso de habilidades y predecirá el siguiente paso:

If pattern repeats (e.g., review → ship → review),
suggest: "Based on your recent pattern, you probably want /ship."

10. Otros diseños destacables

Sistema de gancho

Las tres habilidades: cuidado, congelación y guardia usan ganchos PreToolUse; este es el único mecanismo que puede interceptar antes de que se llame a la herramienta:

• cuidado: Interceptar Bash, marcar rm -rf, DROP TABLE, git push --force
• congelar: intercepta Editar/Escribir y comprueba si la ruta está dentro del rango permitido
• guardia: combina los dos anteriores

Adaptación multiplataforma

El mismo conjunto de plantillas genera archivos de habilidades para diferentes plataformas a través del parámetro --host:

bun run gen:skill-docs --host claude   # Claude Code 格式
bun run gen:skill-docs --host codex    # OpenAI Codex 格式
bun run gen:skill-docs --host kiro     # AWS Kiro 格式
bun run gen:skill-docs --host factory  # Factory Droid 格式

El camino y el tema inicial se adaptan automáticamente y la lógica de la habilidad permanece sin cambios.

Protocolo de estado de finalización

Se debe generar un estado de finalización estandarizado al final de cada habilidad:

DONE                — 全部完成，提供证据
DONE_WITH_CONCERNS  — 完成但有顾虑
BLOCKED             — 无法继续
NEEDS_CONTEXT       — 需要更多信息

Tres reglas de actualización fallidas

If you have attempted a task 3 times without success, STOP and escalate.

Evite que la IA se quede atrapada en un ciclo de reintentos infinito.

Selección de prueba basada en diferencias

Las pruebas E2E cuestan alrededor de $4 cada una (requiere iniciar el agente Claude), por lo que gstack declara los archivos fuente de los que depende cada prueba hasta touchfiles.ts, y solo ejecuta las pruebas afectadas de acuerdo con git diff:

// test/helpers/touchfiles.ts
{
  "qa-workflow": ["qa/SKILL.md.tmpl", "browse/src/server.ts"],
  "ship-flow": ["ship/SKILL.md.tmpl", "scripts/resolvers/preamble.ts"]
}

Resumen: principios de diseño que puedes aprender

De la práctica de ingeniería de gstack, extraje los siguientes principios de diseño que son más valiosos para los desarrolladores de Skills:

1. Generación de plantillas > Sincronización manual: el contenido compartido entre habilidades se genera automáticamente usando plantillas + pasos de compilación, no copiar y pegar
2. Detección pasiva > Detección activa: la detección de actualización está integrada en cada llamada de habilidad, el usuario no lo sabe pero la tasa de cobertura es del 100 %.
3. Agregar registro> Base de datos compleja: el sistema de archivos JSONL + puede cubrir la mayoría de las necesidades de persistencia, es simple y confiable
4. Arranque progresivo > Una configuración: utilice archivos centinela para controlar los pasos de arranque, cada uno de los cuales aparece solo una vez.
5. Puerta precisa > Totalmente automática: defina claramente los límites entre "detener y esperar al usuario" y "continuar automáticamente"
6. Cuantificación de la confianza > Juicio difuso: cada juicio de IA viene con una puntuación de confianza, y la confianza baja se degrada automáticamente.
7. Decaimiento del tiempo > Limpieza manual: la confianza en los registros de aprendizaje decae con el tiempo y el conocimiento obsoleto se desvanece naturalmente
8. LISTA DE PALABRAS PROHIBIDAS > GUÍA DE ESTILO: Una lista directa de palabras prohibidas es mucho más efectiva que "por favor use un tono natural".

Lectura relacionada:

• gstack Concepts — ¿Qué es gstack y qué problemas resuelve?
• Capítulo práctico de gstack — Flujo de trabajo completo desde la instalación hasta la ejecución
• gstack Front-end Skill — Panorama de habilidades de diseño de front-end/UI y flujo de trabajo recomendado
• Concepto de Habilidades de Claude — Comprender el mecanismo subyacente de las Habilidades