anhhung04/tracecat-manage-skills

Gestionar habilidades de Tracecat

Tracecat MCP incluye seis herramientas de habilidad: list_skills, get_skill, prepare_skill_download, prepare_skill_upload, complete_skill_upload y publish_skill.

Las escrituras se preparan (staging), no se insertan en línea. Los bytes de los archivos nunca viajan como argumentos de herramienta: prepare_skill_upload solo toma metadatos (ruta, SHA-256, tamaño, tipo de contenido) y devuelve una URL PUT de corta duración por archivo; los bytes se envían a esas URLs a través de HTTP simple; complete_skill_upload luego adjunta los blobs preparados y reemplaza el borrador. No busque un argumento content_base64 en línea y nunca lea bytes de archivos en el contexto para enviarlos.

El asistente empaquetado elimina las partes propensas a errores manuales: el recorrido seguro del directorio, el rechazo de enlaces simbólicos, la aplicación del archivo SKILL.md raíz y los resúmenes SHA-256.

Subir una habilidad

Los mismos cuatro pasos crean una habilidad y reemplazan una existente. La única diferencia es qué argumentos de identidad toma prepare_skill_upload.

1. Resuelva el espacio de trabajo objetivo con list_workspaces, luego llame a list_skills. Para una habilidad nueva, confirme que el nombre está libre (omitir skill_id siempre crea una nueva fila, por lo que una segunda creación genera dos habilidades con el mismo name y diferentes slugs). Para una habilidad existente, tome su skill_id.

2. Construya el array de metadatos:

   python3 <directorio-de-esta-habilidad>/scripts/upload_skill_files.py metadata <directorio-local-de-la-habilidad>
   

   Imprime el array files textualmente: una entrada por archivo con path, sha256, size_bytes y content_type. Sin contenido de archivos.

3. Llame a prepare_skill_upload con workspace_id y ese array files, más:

   • name (y opcionalmente description) y sin skill_id, para crear una habilidad; o
   • skill_id y sin name/description, para reemplazar el borrador de una habilidad existente.

   Para una creación, pase el mismo name que declara el frontmatter local: el servidor fusiona name y description en el frontmatter de SKILL.md almacenado antes de validar, por lo que un argumento no coincidente reescribe silenciosamente lo que se almacena.

   La respuesta incluye skill_id, base_revision, created y, por archivo, upload_id, upload_url, method, headers y expires_at.

4. Envíe PUT de los bytes sin procesar de cada archivo a su upload_url con el método y los encabezados devueltos, directamente desde el disco. Las URLs son de corta duración; verifique expires_at y vuelva a preparar en lugar de reintentar una URL obsoleta.

5. Llame a complete_skill_upload con workspace_id, skill_id, el base_revision del paso 3 y un array files de {"path": ..., "upload_id": ...} para cada archivo. Esto reemplaza el borrador y no publica.

6. Llame a publish_skill con el skill_id cuando la habilidad deba poder adjuntarse a presets. Un borrador no publicado no se puede vincular.

base_revision es un guardián de concurrencia. Un draft_revision_conflict significa que alguien más editó el borrador desde el paso 3: llame a get_skill para ver la draft_revision actual y qué eliminaría un reemplazo completo del árbol, luego vuelva a preparar.

Actualizar una habilidad en vivo

Una corrección que se detiene después de complete_skill_upload no cambia nada de lo que ejecuta un agente. Tres pasos, en orden:

1. prepare_skill_upload con skill_id → PUT los bytes → complete_skill_upload. Esto reemplaza el borrador. No publica.
2. publish_skill con el mismo skill_id. Las habilidades tienen versiones; esto crea una nueva versión inmutable y mueve el current_version_id de la habilidad.
3. update_agent_preset con la lista skills del preset consumidor (las mismas entradas {"skill_id": ...} que ya tenía). Cada vinculación se re-fija a la versión publicada actual de esa habilidad en el momento de la escritura, por lo que un preset vinculado antes del paso 2 sigue ejecutando la versión antigua hasta que esta llamada lo reescribe.

Omitir el paso 3 es el fallo clásico: la nueva versión existe, el preset nunca la ve.

Verifique volviendo a obtener los datos. get_skill sin path devuelve el manifiesto del borrador (rutas, resúmenes, tamaños, draft_revision, is_publishable, validation_errors) y nunca el contenido de los archivos; get_skill con path lee un archivo, en línea cuando es texto UTF-8 pequeño. list_skills muestra el current_version_id de la habilidad; get_agent_preset muestra skills[].skill_version_id y skills[].skill_version. Confirme que ambos han cambiado.

Este es un trabajo rutinario y reversible. Cada versión publicada es inmutable y aún se puede vincular, por lo que una mala actualización se deshace publicando un árbol corregido y re-vinculando. Hágalo en lugar de narrar el riesgo; reserve la precaución para operaciones que realmente no se pueden deshacer.

Declarar las herramientas de la habilidad

Una habilidad lleva sus propias herramientas. Declárelas en el frontmatter de SKILL.md raíz bajo metadata.tools, como nombres de acciones de registro o entradas mcp.<slug> / mcp.<slug>.<tool>, hasta 64 por habilidad:

---
name: slack-triage
description: Publicar y gestionar actualizaciones de hilos en Slack.
metadata:
  tools:
    - tools.slack.post_message
    - tools.slack.list_replies
---

Cada preset al que se adjunte la habilidad recibe esas herramientas además de su propia lista de permisos actions. Se conceden tan pronto como el preset se resuelve, independientemente de si el modelo abre la habilidad; solo las instrucciones de la habilidad se cargan bajo demanda.

Prefiera esto sobre listar las mismas herramientas en el actions de cada preset cuando las herramientas se agrupen de forma natural y varios agentes las reutilicen (una edición y una republicación actualizan cada preset consumidor). Mantenga una herramienta en el actions del preset cuando sea específica de ese agente.

Un inconveniente: el filtro namespaces de un preset se aplica a las herramientas de registro en la unión y bloquea silenciosamente las que están fuera de él. Después de adjuntar una habilidad a un preset con restricción de espacios de nombres, verifique tool_policy.blocked_tools en get_agent_preset. Las herramientas MCP que declara una habilidad (mcp.<slug> / mcp.<slug>.<tool>) no son filtradas por namespaces y no aparecen allí.

Cambiar metadata.tools cambia lo que los agentes pueden ejecutar, por lo que sigue los mismos tres pasos que cualquier otra corrección: reemplazar el borrador, publish_skill, luego update_agent_preset para re-fijar el vínculo. Una lectura del preset resultante muestra las herramientas concedidas como una lista plana en tool_policy.actions, sin procedencia por habilidad: la unión es lo que puede verificar.

Tamaño

Los bytes ya no pasan por el contexto del modelo, pero cada archivo aún tiene un límite de tamaño del lado del servidor y un árbol completo sigue siendo más fácil de revisar cuando es pequeño y solo contiene texto.

• Prefiera Markdown, YAML y scripts. Aloje un activo binario grande en otro lugar y haga referencia a él.
• Mueva los detalles extensos a archivos references/ que el agente lee bajo demanda, en lugar de a SKILL.md.
• Si un árbol es demasiado grande para razonar sobre él, divida la habilidad en dos. No divida un árbol en varias llamadas a complete_skill_upload: cada llamada reemplaza el borrador completo, por lo que una llamada parcial elimina todo lo que omite.

Reglas estrictas

• Omitir skill_id crea; pasarlo reemplaza. Nunca cree contra un nombre que ya existe: el reintento del slug hace que el duplicado tenga éxito en lugar de fallar.
• Cada escritura reemplaza el borrador completo. Los archivos ausentes del directorio local se eliminan de la habilidad. Envíe siempre el árbol completo.
• Suba cada archivo preparado antes de llamar a complete_skill_upload y pase cada ruta de vuelta con su upload_id.
• Nunca incruste bytes de archivos o base64 en un argumento de herramienta, y nunca lea los bytes de una URL de carga o descarga en el contexto. Transfiera hacia y desde el disco.
• Publicar no mueve los vínculos de preset existentes. Reescriba la lista skills del preset para recoger una nueva versión.
• Rechace archivos y directorios con enlaces simbólicos, y nunca envíe contenido desde fuera de la raíz de la habilidad seleccionada. El asistente lo aplica; no lo evite.
• El archivo raíz debe ser exactamente SKILL.md, en el nivel superior, y UTF-8 válido. El servidor rechaza un conjunto de archivos sin él.
• Si el cliente no puede ejecutar scripts locales, dígalo y dé al usuario el comando auxiliar para ejecutar. No sustituya resúmenes generados por el modelo.

Referencias

• Lea references/upload-contract.md para conocer las formas literales de solicitud y respuesta y qué protege y qué no protege esta ruta.
• Lea references/troubleshooting.md cuando una carga, publicación o re-vinculación de preset no se concrete.