Plugin del taller de habilidades

El Taller de Habilidades es experimental. Está deshabilitado por defecto, sus heurísticas de captura y las indicaciones del revisor pueden cambiar entre versiones, y las escrituras automáticas deben usarse solo en espacios de trabajo de confianza después de revisar primero la salida del modo pendiente.

El Taller de Habilidades es la memoria de procedimientos para las habilidades del espacio de trabajo. Permite que un agente convierta flujos de trabajo reutilizables, correcciones de usuario, soluciones difíciles de lograr y problemas recurrentes en archivos SKILL.md en:

<workspace>/skills/<skill-name>/SKILL.md

Esto es diferente de la memoria a largo plazo:

Memoria almacena hechos, preferencias, entidades y contexto pasado.
Habilidades almacenan procedimientos reutilizables que el agente debe seguir en tareas futuras.
Taller de Habilidades es el puente desde una interacción útil hasta una habilidad duradera del espacio de trabajo, con comprobaciones de seguridad y aprobación opcional.

El Taller de Habilidades es útil cuando el agente aprende un procedimiento como:

cómo validar activos de GIF animados de origen externo
cómo reemplazar activos de capturas de pantalla y verificar dimensiones
cómo ejecutar un escenario de QA específico del repositorio
cómo depurar un fallo recurrente del proveedor
cómo reparar una nota de flujo de trabajo local obsoleta

No está destinado para:

hechos como “al usuario le gusta el azul”
memoria autobiográfica amplia
archivo de transcripciones sin procesar
secretos, credenciales o texto de indicación oculto
instrucciones únicas que no se repetirán

Estado predeterminado

El plugin incluido es experimental y está deshabilitado por defecto a menos que se haya habilitado explícitamente en plugins.entries.skill-workshop.

El manifiesto del plugin no establece enabledByDefault: true. El valor predeterminado de enabled: true dentro del esquema de configuración del plugin se aplica solo después de que la entrada del plugin ya ha sido seleccionada y cargada.

Experimental significa:

el plugin tiene soporte suficiente para pruebas opt-in y uso interno (dogfooding)
el almacenamiento de propuestas, los umbrales del revisor y las heurísticas de captura pueden evolucionar
la aprobación pendiente es el modo de inicio recomendado
la aplicación automática es para configuraciones personales/de espacio de trabajo confiables, no para entornos compartidos o hostiles con mucha entrada externa

Habilitar

Configuración mínima segura:

{
  plugins: {
    entries: {
      "skill-workshop": {
        enabled: true,
        config: {
          autoCapture: true,
          approvalPolicy: "pending",
          reviewMode: "hybrid",
        },
      },
    },
  },
}

Con esta configuración:

la herramienta skill_workshop está disponible
las correcciones reutilizables explícitas se ponen en cola como propuestas pendientes
las pasadas del revisor basadas en umbrales pueden proponer actualizaciones de habilidades
no se escribe ningún archivo de habilidad hasta que se aplica una propuesta pendiente

Use las escrituras automáticas solo en espacios de trabajo de confianza:

{
  plugins: {
    entries: {
      "skill-workshop": {
        enabled: true,
        config: {
          autoCapture: true,
          approvalPolicy: "auto",
          reviewMode: "hybrid",
        },
      },
    },
  },
}

approvalPolicy: "auto" todavía usa el mismo escáner y ruta de cuarentena. No aplica propuestas con hallazgos críticos.

Configuración

Clave	Predeterminado	Rango / valores	Significado
`enabled`	`true`	booleano	Habilita el complemento después de cargar la entrada del complemento.
`autoCapture`	`true`	booleano	Habilita la captura/revisión posterior al turno en turnos exitosos del agente.
`approvalPolicy`	`"pending"`	`"pending"`, `"auto"`	Poner en cola propuestas o escribir propuestas seguras automáticamente.
`reviewMode`	`"hybrid"`	`"off"`, `"heuristic"`, `"llm"`, `"hybrid"`	Elige captura de corrección explícita, revisor LLM, ambos o ninguno.
`reviewInterval`	`15`	`1..200`	Ejecutar el revisor después de esta cantidad de turnos exitosos.
`reviewMinToolCalls`	`8`	`1..500`	Ejecutar el revisor después de esta cantidad de llamadas a herramientas observadas.
`reviewTimeoutMs`	`45000`	`5000..180000`	Tiempo de espera para la ejecución del revisor integrado.
`maxPending`	`50`	`1..200`	Máximo de propuestas pendientes/en cuarentena mantenidas por espacio de trabajo.
`maxSkillBytes`	`40000`	`1024..200000`	Tamaño máximo de archivo de habilidad/soporte generado.

Perfiles recomendados:

// Conservative: explicit tool use only, no automatic capture.
{
  autoCapture: false,
  approvalPolicy: "pending",
  reviewMode: "off",
}

// Review-first: capture automatically, but require approval.
{
  autoCapture: true,
  approvalPolicy: "pending",
  reviewMode: "hybrid",
}

// Trusted automation: write safe proposals immediately.
{
  autoCapture: true,
  approvalPolicy: "auto",
  reviewMode: "hybrid",
}

// Low-cost: no reviewer LLM call, only explicit correction phrases.
{
  autoCapture: true,
  approvalPolicy: "pending",
  reviewMode: "heuristic",
}

Rutas de captura

Skill Workshop tiene tres rutas de captura.

Sugerencias de herramientas

El modelo puede llamar a skill_workshop directamente cuando ve un procedimiento reutilizable o cuando el usuario le pide que guarde/actualice una habilidad.

Esta es la ruta más explícita y funciona incluso con autoCapture: false.

Captura heurística

Cuando autoCapture está habilitado y reviewMode es heuristic o hybrid, el complemento escanea los turnos exitosos en busca de frases explícitas de corrección del usuario:

next time
from now on
remember to
make sure to
always ... use/check/verify/record/save/prefer
prefer ... when/for/instead/use
when asked

La heurística crea una propuesta a partir de la última instrucción del usuario que coincida. Utiliza pistas de temas para elegir nombres de habilidades para flujos de trabajo comunes:

tareas de GIF animado -> animated-gif-workflow
tareas de captura de pantalla o activos -> screenshot-asset-workflow
tareas de control de calidad o escenarios -> qa-scenario-workflow
tareas de Pull Requests de GitHub -> github-pr-workflow
alternativa -> learned-workflows

La captura heurística es intencionalmente estrecha. Está diseñada para correcciones claras y notas de procesos repetibles, no para el resumen general de transcripciones.

Revisor LLM

Cuando autoCapture está habilitado y reviewMode es llm o hybrid, el complemento ejecuta un revisor integrado compacto después de alcanzar los umbrales.

El revisor recibe:

el texto de la transcripción reciente, limitado a los últimos 12,000 caracteres
hasta 12 habilidades existentes del espacio de trabajo
hasta 2,000 caracteres de cada habilidad existente
instrucciones solo en formato JSON

El revisor no tiene herramientas:

disableTools: true
toolsAllow: []
disableMessageTool: true

El revisor devuelve { "action": "none" } o una propuesta. El campo action es create, append o replace - prefiera append/replace cuando ya exista una habilidad relevante; use create solo cuando ninguna habilidad existente se ajuste.

Ejemplo de create:

{
  "action": "create",
  "skillName": "media-asset-qa",
  "title": "Media Asset QA",
  "reason": "Reusable animated media acceptance workflow",
  "description": "Validate externally sourced animated media before product use.",
  "body": "## Workflow\n\n- Verify true animation.\n- Record attribution.\n- Store a local approved copy.\n- Verify in product UI before final reply."
}

append añade section + body. replace intercambia oldText por newText en la habilidad nombrada.

Ciclo de vida de la propuesta

Cada actualización generada se convierte en una propuesta con:

id
createdAt
updatedAt
workspaceDir
agentId opcional
sessionId opcional
skillName
title
reason
source: tool, agent_end o reviewer
status
change
scanFindings opcional
quarantineReason opcional

Estados de las propuestas:

pending - esperando aprobación
applied - escrito en <workspace>/skills
rejected - rechazado por el operador/modelo
quarantined - bloqueado por hallazgos críticos del escáner

El estado se almacena por área de trabajo en el directorio de estado de Gateway:

<stateDir>/skill-workshop/<workspace-hash>.json

Las propuestas pendientes y en cuarentena se deduplican por nombre de habilidad y carga de cambio. El almacén mantiene las propuestas pendientes/en cuarentena más recientes hasta maxPending.

Referencia de herramientas

El complemento registra una herramienta de agente:

skill_workshop

`status`

Cuenta propuestas por estado para el área de trabajo activa.

{ "action": "status" }

Formato del resultado:

{
  "workspaceDir": "/path/to/workspace",
  "pending": 1,
  "quarantined": 0,
  "applied": 3,
  "rejected": 0
}

`list_pending`

Lista las propuestas pendientes.

{ "action": "list_pending" }

Para listar otro estado:

{ "action": "list_pending", "status": "applied" }

Valores status válidos:

pending
applied
rejected
quarantined

`list_quarantine`

Lista las propuestas en cuarentena.

{ "action": "list_quarantine" }

Use esto cuando la captura automática parece no hacer nada y los registros mencionan skill-workshop: quarantined <skill>.

`inspect`

Obtiene una propuesta por id.

{
  "action": "inspect",
  "id": "proposal-id"
}

`suggest`

Crear una propuesta. Con approvalPolicy: "pending" (predeterminado), esto pone en cola en lugar de escribir.

{
  "action": "suggest",
  "skillName": "animated-gif-workflow",
  "title": "Animated GIF Workflow",
  "reason": "User established reusable GIF validation rules.",
  "description": "Validate animated GIF assets before using them.",
  "body": "## Workflow\n\n- Verify the URL resolves to image/gif.\n- Confirm it has multiple frames.\n- Record attribution and license.\n- Avoid hotlinking when a local asset is needed."
}

Solicitar escritura inmediata en modo automático (apply: true)

{
  "action": "suggest",
  "apply": true,
  "skillName": "animated-gif-workflow",
  "description": "Validate animated GIF assets before using them.",
  "body": "## Workflow\n\n- Verify true animation.\n- Record attribution."
}

Con approvalPolicy: "pending", apply: true todavía pone en cola la propuesta. Revísela y luego use la acción apply después de la aprobación.

Forzar pendiente bajo política automática (apply: false)

{
  "action": "suggest",
  "apply": false,
  "skillName": "screenshot-asset-workflow",
  "description": "Screenshot replacement workflow.",
  "body": "## Workflow\n\n- Verify dimensions.\n- Optimize the PNG.\n- Run the relevant gate."
}

Añadir a una sección con nombre

{
  "action": "suggest",
  "skillName": "qa-scenario-workflow",
  "section": "Workflow",
  "description": "QA scenario workflow.",
  "body": "- For media QA, verify generated assets render and pass final assertions."
}

Reemplazar texto exacto

{
  "action": "suggest",
  "skillName": "github-pr-workflow",
  "oldText": "- Check the PR.",
  "newText": "- Check unresolved review threads, CI status, linked issues, and changed files before deciding."
}

`apply`

Aplicar una propuesta pendiente.

Con approvalPolicy: "pending", esta acción solicita la aprobación del operador antes de escribir la habilidad del espacio de trabajo.

{
  "action": "apply",
  "id": "proposal-id"
}

apply rechaza las propuestas en cuarentena:

quarantined proposal cannot be applied

`reject`

Marcar una propuesta como rechazada.

{
  "action": "reject",
  "id": "proposal-id"
}

`write_support_file`

Escribir un archivo de soporte dentro de un directorio de habilidad existente o propuesto.

Directorios de soporte de nivel superior permitidos:

references/
templates/
scripts/
assets/

Ejemplo:

{
  "action": "write_support_file",
  "skillName": "release-workflow",
  "relativePath": "references/checklist.md",
  "body": "# Release Checklist\n\n- Run release docs.\n- Verify changelog.\n"
}

Los archivos de soporte tienen alcance de espacio de trabajo, verificación de ruta, límite de bytes por maxSkillBytes, se escanean y se escriben de forma atómica.

Escrituras de habilidades

Skill Workshop escribe solo bajo:

<workspace>/skills/<normalized-skill-name>/

Los nombres de las habilidades se normalizan:

en minúsculas
las ejecuciones que no son [a-z0-9_-] se convierten en -
se eliminan los caracteres no alfanuméricos al principio y al final
la longitud máxima es de 80 caracteres
el nombre final debe coincidir con [a-z0-9][a-z0-9_-]{1,79}

Para create:

si la habilidad no existe, Skill Workshop escribe un nuevo SKILL.md
si ya existe, Skill Workshop agrega el cuerpo a ## Workflow

Para append:

si la habilidad existe, Skill Workshop agrega a la sección solicitada
si no existe, Skill Workshop crea una habilidad mínima y luego agrega

Para replace:

la habilidad ya debe existir
oldText debe estar presente exactamente
solo se reemplaza la primera coincidencia exacta

Todas las escrituras son atómicas y actualizan la instantánea de habilidades en memoria inmediatamente, por lo que la habilidad nueva o actualizada puede hacerse visible sin reiniciar el Gateway.

Modelo de seguridad

Skill Workshop tiene un escáner de seguridad en el contenido generado de SKILL.md y archivos de soporte.

Los hallazgos críticos ponen en cuarentena las propuestas:

ID de regla	Bloquea el contenido que…
`prompt-injection-ignore-instructions`	dice al agente que ignore instrucciones previas/superiores
`prompt-injection-system`	hace referencia a los prompts del sistema, mensajes de desarrollador o instrucciones ocultas
`prompt-injection-tool`	anula a omitir el permiso/aprobación de la herramienta
`shell-pipe-to-shell`	incluye `curl`/`wget` canalizado hacia `sh`, `bash` o `zsh`
`secret-exfiltration`	parece enviar datos de variables de entorno/proceso a través de la red

Los hallazgos de advertencia se conservan pero no bloquean por sí mismos:

ID de regla	Advierte sobre…
`destructive-delete`	comandos de estilo `rm -rf` amplios
`unsafe-permissions`	uso de permisos de estilo `chmod 777`

Propuestas en cuarentena:

mantienen scanFindings
mantienen quarantineReason
aparecen en list_quarantine
no se pueden aplicar a través de apply

Para recuperarse de una propuesta en cuarentena, cree una nueva propuesta segura con el contenido no seguro eliminado. No edite el JSON del almacén manualmente.

Guía del prompt

Cuando está habilitado, Skill Workshop inyecta una sección corta de prompt que indica al agente que use skill_workshop para memoria de procedimientos duradera.

La guía enfatiza:

procedimientos, no datos/hechos/preferencias
correcciones del usuario
procedimientos exitosos no obvios
errores recurrentes
reparación de habilidades obsoletas/insuficientes/incorrectas mediante anexión/reemplazo
guardar procedimientos reutilizables después de bucles largos de herramientas o arreglos difíciles
texto de habilidad imperativo corto
sin volcados de transcripciones

El texto del modo de escritura cambia con approvalPolicy:

modo pendiente: poner sugerencias en cola; usar apply después de la aprobación explícita
modo automático: aplicar actualizaciones de habilidades del área de trabajo seguras a menos que apply: false ponga en cola en su lugar

Costos y comportamiento en tiempo de ejecución

La captura heurística no invoca a ningún modelo.

La revisión LLM utiliza una ejecución integrada en el modelo del agente activo/predeterminado. Se basa en umbrales, por lo que de forma predeterminada no se ejecuta en cada turno.

El revisor:

utiliza el mismo contexto de proveedor/modelo configurado cuando está disponible
recurre a los valores predeterminados del agente en tiempo de ejecución
tiene reviewTimeoutMs
utiliza un contexto de arranque ligero
no tiene herramientas
no escribe nada directamente
solo puede emitir una propuesta que pasa por el escáner normal y la ruta de aprobación/cuarentena

Si el revisor falla, expira el tiempo de espera o devuelve JSON no válido, el complemento registra un mensaje de advertencia/depuración y omite ese pase de revisión.

Patrones operativos

Use Skill Workshop cuando el usuario diga:

“la próxima vez, haz X”
“a partir de ahora, prefiere Y”
“asegúrate de verificar Z”
“guarda esto como un flujo de trabajo”
“esto tomó un tiempo; recuerda el proceso”
“actualiza la habilidad local para esto”

Texto de habilidad bueno:

## Workflow

- Verify the GIF URL resolves to `image/gif`.
- Confirm the file has multiple frames.
- Record source URL, license, and attribution.
- Store a local copy when the asset will ship with the product.
- Verify the local asset renders in the target UI before final reply.

Texto de habilidad pobre:

The user asked about a GIF and I searched two websites. Then one was blocked by
Cloudflare. The final answer said to check attribution.

Razones por las que la versión pobre no debería guardarse:

con forma de transcripción
no imperativo
incluye detalles ruidosos de una sola vez
no le dice al siguiente agente qué hacer

Depuración

Compruebe si el complemento está cargado:

openclaw plugins list --enabled

Verifique los recuentos de propuestas desde un contexto de agente/herramienta:

{ "action": "status" }

Inspeccione las propuestas pendientes:

{ "action": "list_pending" }

Inspeccione las propuestas en cuarentena:

{ "action": "list_quarantine" }

Síntomas comunes:

Síntoma	Causa probable	Comprobar
La herramienta no está disponible	La entrada del complemento no está habilitada	`plugins.entries.skill-workshop.enabled` y `openclaw plugins list`
No aparece ninguna propuesta automática	`autoCapture: false`, `reviewMode: "off"` o umbrales no cumplidos	Configuración, estado de la propuesta, registros de Gateway
La heurística no capturó	Las palabras del usuario no coincidieron con los patrones de corrección	Use `skill_workshop.suggest` explícito o habilite el revisor LLM
El revisor no creó una propuesta	El revisor devolvió `none`, JSON no válido o expiró el tiempo	Registros de Gateway, `reviewTimeoutMs`, umbrales
La propuesta no se aplica	`approvalPolicy: "pending"`	`list_pending`, entonces `apply`
La propuesta desapareció de pendientes	Propuesta duplicada reutilizada, poda máxima de pendientes, o fue aplicada/rechazada/puesta en cuarentena	`status`, `list_pending` con filtros de estado, `list_quarantine`
El archivo de habilidad existe pero el modelo lo omite	La instantánea de habilidad no se actualizó o el filtrado de habilidades la excluye	Estado de `openclaw skills` y elegibilidad de habilidades del espacio de trabajo

Registros relevantes:

skill-workshop: queued <skill>
skill-workshop: applied <skill>
skill-workshop: quarantined <skill>
skill-workshop: heuristic capture skipped: ...
skill-workshop: reviewer skipped: ...
skill-workshop: reviewer found no update

Escenarios de QA

Escenarios de QA respaldados por repositorio:

qa/scenarios/plugins/skill-workshop-animated-gif-autocreate.md
qa/scenarios/plugins/skill-workshop-pending-approval.md
qa/scenarios/plugins/skill-workshop-reviewer-autonomous.md

Ejecutar la cobertura determinista:

pnpm openclaw qa suite \
  --scenario skill-workshop-animated-gif-autocreate \
  --scenario skill-workshop-pending-approval \
  --concurrency 1

Ejecutar la cobertura del revisor:

pnpm openclaw qa suite \
  --scenario skill-workshop-reviewer-autonomous \
  --concurrency 1

El escenario del revisor es intencionalmente separado porque habilita reviewMode: "llm" y ejercita el pase del revisor incrustado.

Cuándo no habilitar la aplicación automática

Evite approvalPolicy: "auto" cuando:

el espacio de trabajo contiene procedimientos confidenciales
el agente está trabajando en entrada no confiable
las habilidades se comparten en un equipo amplio
todavía está ajustando los mensajes o las reglas del escáner
el modelo maneja frecuentemente contenido web/correo hostil

Use el modo pendiente primero. Cambie al modo automático solo después de revisar el tipo de habilidades que el agente propone en ese espacio de trabajo.