rundesk-ai/rundesk-cli

Escribir habilidades

Reutilizar el propietario existente

Inspecciona los catálogos de habilidades existentes antes de crear un paquete. Para trabajo en repositorios, busca en el catálogo objetivo y en cada catálogo de origen relevante dentro del espacio de trabajo autorizado. Para trabajo autorizado de librería en vivo, usa el catálogo y los listados de habilidades de Rundesk; no abras la librería en vivo para eludir el límite de acceso de la tarea. Lee las descripciones de coincidencias plausibles, luego sus cuerpos y referencias relevantes antes de decidir.

Extiende al propietario existente cuando la capacidad solicitada comparta su intención de usuario, flujo de trabajo y autoridad. Añade allí un script de soporte, referencia o prueba en lugar de crear una segunda superficie de ruteo. Crea una nueva habilidad solo cuando la capacidad necesite ruteo, juicio, autoridad o prueba distintos; registra esa distinción para que un nombre cercano no sea tratado como justificación por sí mismo.

Elegir el artefacto

• Una habilidad es el límite de instrucción: cuándo actuar, qué juicio aplicar, qué procedimiento seguir y cómo probar el resultado.
• Un script de flujo de trabajo es el mecanismo determinista para transformación, validación u orquestación local repetida.
• Una integración añade un límite de servicio externo: credenciales, cuentas, fallos de red, permisos o efectos remotos.

Mantén la automatización única en su proyecto y un comando repetido privado de un agente en el área de scripts de ese agente. Empaqueta un script en una habilidad solo cuando futuros turnos necesiten ruteo o juicio para usarlo. No reemplaces código determinista con prosa que un agente deba reinterpretar.

Lee Scripts de flujo de trabajo reutilizables antes de enviar cualquier script reutilizable. Lee también Integraciones con servicios externos cuando use credenciales, perfiles, OAuth, una red o efectos remotos.

Colocarlo de forma segura

Crea una habilidad privada en local solo cuando la creación o instalación en vivo esté autorizada. Para un borrador, revisión, cambio en el repositorio o prueba aislada, mantente en el espacio de trabajo nombrado o directorio temporal; no inspecciones ni modifiques la librería en vivo para descubrir dónde podría ir el resultado más tarde.

Para una habilidad privada autorizada, pídele a Rundesk la librería en lugar de derivarla de RUNDESK_HOME o incrustar una ruta absoluta. Reemplaza el nombre de ejemplo:

skill_name=release-notes
skill_library=$("$RUNDESK_COMMAND" skills | sed -n '1s/^skills in //p')
test -n "$skill_library" || exit 1
mkdir -p "$skill_library/local/$skill_name"

Escribe <libreria>/local/<nombre>/SKILL.md, luego concédelo al agente nombrado:

"$RUNDESK_COMMAND" skills grant "$RUNDESK_AGENT" local/release-notes

La concesión se vuelve visible en el próximo turno del agente, no en el actual. Lee Publicar un catálogo de habilidades antes de crear una habilidad para otras instalaciones; las habilidades publicadas pertenecen a un repositorio de catálogo, no a local.

Usar solo la forma necesaria

<nombre>/
├── SKILL.md          requerido: ruteo y procedimiento central
├── rundesk.json      opcional: valores de entorno requeridos
├── scripts/          opcional: comandos reutilizables
├── tests/            opcional: contratos de script cuando no hay área de prueba de catálogo que los posea
├── references/       opcional: detalle cargado condicionalmente
└── assets/           opcional: material copiado o de salida

Crea rutas opcionales solo con contenido. Omite README, registro de cambios, guía de instalación e historial de creación.

Escribir el ruteo primero

El frontmatter solo tiene name y description.

• Haz coincidir name con el directorio. Usa como máximo 64 letras minúsculas, dígitos y guiones simples.
• Rutea por la intención del usuario, incluyendo solicitudes indirectas que quizás no nombren la habilidad. Comienza con "Usar cuando", "Aplicar cuando" o lenguaje de aplicabilidad equivalente; las frases de solicitud no son desencadenantes.
• Apunta a dos oraciones cortas: aplicabilidad, luego el flujo de trabajo especializado o conocimiento proporcionado. Añade "No usar" solo para un casi acierto probable. Incluye solo conceptos necesarios para rutear antes de que se cargue el cuerpo. Omite pasos, pruebas, afirmaciones de beneficios y detalles de implementación; nombra un tipo de archivo, herramienta o formato solo cuando determina si la habilidad debe activarse.
• Usa la descripción más corta que aún rutee correctamente; 1024 caracteres es un techo, no un objetivo. Pon cada desencadenante allí porque cada titular paga por él en cada turno y el cuerpo no está disponible hasta que el ruteo tenga éxito.

# Mal: incrusta implementación y verificación que no pueden ayudar al ruteo.
description: Usar al crear notas de versión. Lee el historial de Git, escribe Markdown, agrupa commits, verifica enlaces, ejecuta validación y produce versiones concisas internas y públicas con formato preciso.

# Bien: establece la intención, el juicio proporcionado y solo el límite más cercano.
description: Usar al preparar notas de versión a partir de cambios enviados al repositorio. Proporciona un flujo de trabajo enfocado en la audiencia basado en historial verificado. No usar para planes no publicados.

Mantener solo guía de comportamiento

Usa pasos imperativos en orden de ejecución. Asume que el lector puede razonar, editar y usar herramientas ordinarias. Mantén una oración solo cuando cambie la ejecución, evite un fallo probable o rutee detalle necesario.

• Mantén el procedimiento central, un valor predeterminado sólido y trampas no obvias en SKILL.md.
• Usa comandos exactos para operaciones frágiles; usa juicio conciso donde varios enfoques funcionen.
• Explica el fallo que una restricción previene en lugar de añadir énfasis sin explicación.
• Introduce cada referencia con cuándo leerla. Mantén una fuente de verdad; enlaza en lugar de volver a declarar.
• Elimina antecedentes, historial de proceso, afirmaciones desactualizadas y reglas ya cargadas en otro lugar.
• Distingue contratos observados de valores predeterminados recomendados. Fundamenta restricciones técnicas y enseña trampas reales como síntoma, causa, reemplazo y prueba observable.

Mantén SKILL.md por debajo de 500 líneas; mueve el detalle condicional un nivel hacia referencias enlazadas.

Presupuestar el contexto

Parte	Costo de tokens	Mantener allí
description	cada turno	desencadenante completo más corto
SKILL.md	después del ruteo	procedimiento central, valores predeterminados, trampas
references/	cuando se lee	detalle condicional y ejemplos más grandes
scripts/	la salida entra al contexto	trabajo determinista con salida acotada
tests/	solo validación	contratos ejecutables y casos límite
assets/	cuando se usa	plantillas y material de salida

Prefiere ejemplos cortos. Acota la salida del script a lo que la siguiente decisión necesite.

Probar toda la habilidad

1. Valida el nombre del directorio, el nombre del frontmatter, la sintaxis de la descripción y los límites.

2. Cuando se necesite una concesión, aplícala y verifica el siguiente turno:

   "$RUNDESK_COMMAND" skills list "$RUNDESK_AGENT"
   "$RUNDESK_COMMAND" skills doctor "$RUNDESK_AGENT"
   

3. Ejecuta la matriz de casos límite propiedad de la referencia y el punto de entrada ejecutable directo de cada script.

4. En diferentes turnos nuevos, prueba una solicitud directa, una solicitud indirecta y un casi acierto cercano. Confirma que el cuerpo y las referencias requeridas se carguen antes del trabajo; corrige el ruteo por categoría, no por frases de solicitud copiadas.

5. Para una habilidad sustancial, compara la misma tarea con una línea base nueva sin la habilidad. Luego haz que un agente de prueba separado la use sin la implementación esperada. Revisa artefactos y comandos directamente; el resumen del agente no es prueba. Elimina guía que no genere mejora material.

6. Revisa la escritura generada por separado de la corrección ejecutable: precisión del ruteo, orden de ejecución, juicio útil, concisión, duplicación y disciplina de referencia. Las pruebas de script verdes no prueban la calidad de la escritura. Fundamenta o observa promesas fácticas; prueba afirmaciones ejecutables y acota verdades parciales. Desafía afirmaciones semánticas con un contraejemplo adversario que preserve agregados convenientes mientras cambia la relación real o el resultado—las comprobaciones de mutación no pueden reparar un oráculo de prueba incorrecto. Revisa toda la interfaz, incluyendo éxito vacío, evidencia duplicada y cada sección de salida dependiente de datos.