Creación de Skills

Skill utilizado para crear o mantener los Skills de primer nivel de AgentDock. El cuerpo del Skill es un documento de instrucciones legible por el modelo; las herramientas se encargan de la verificación real, edición, ejecución de comandos, empaquetado, instalación y validación.

El Skill objetivo debe constar de dos partes:

Contrato portátil principal
+
Instrucciones de adaptación al host (opcional)

Al eliminar las instrucciones de adaptación específicas de AgentDock, el flujo de trabajo del Skill, las referencias dentro del paquete, el contrato de variables de entorno y los scripts auxiliares deben seguir siendo completamente funcionales.

Cuándo usar

Utilice este Skill para:

Crear un nuevo Skill de primer nivel;
Modificar, refactorizar o actualizar un Skill existente;
Ajustar la descripción de activación, el flujo del cuerpo, los materiales de referencia o los scripts auxiliares;
Agregar pruebas, ejemplos, restricciones de seguridad y comprobaciones de portabilidad;
Incrementar la versión y completar la verificación entre el código fuente y la versión activa actual.

No utilice este Skill para revisiones de seguridad formales de Skills de terceros, configuración de credenciales reales o reversión de versiones instaladas. Eso pertenece a skill-installation.

Principios fundamentales

Primero defina cuándo debe el modelo seleccionar este Skill, luego redacte el cuerpo.
El Skill solo describe métodos, límites y selección de herramientas; no asume la responsabilidad de la ejecución unificada.
El contrato principal del Skill debe ser independiente del host; use rutas relativas para los archivos dentro del paquete; el entorno lo inyecta el host en ejecución.
Para Skills simples, priorice tener un solo archivo SKILL.md; solo agregue referencias, scripts o pruebas cuando sea realmente necesario.
Después de modificar el cuerpo, las referencias, los scripts o el comportamiento, debe incrementar la versión semántica.
El contenido con el mismo nombre y la misma versión debe permanecer inmutable.
Los valores de entorno, el estado del dispositivo y los datos de ejecución no deben incluirse en el paquete del Skill.
Todas las verificaciones deben realizarse sobre la versión actualmente instalada y activada, no solo sobre el directorio del código fuente.
Los Skills de primer nivel deben pasar el lint de este Skill; no basta con pasar la validación de instalación del paquete.

La especificación completa se encuentra en references/skill-package-spec.md dentro del paquete.

Flujo estándar

1. Comprender los requisitos y las condiciones de activación

Primero, aclare:

El problema real que el usuario necesita resolver;
Ante qué solicitudes debe el modelo seleccionar este Skill;
Qué tareas adyacentes no pertenecen a este Skill;
Qué herramientas reales deben invocarse;
Si se necesitan scripts auxiliares, materiales de referencia o pruebas;
Si implica operaciones de red, escritura, eliminación, credenciales o acciones de alto riesgo.

No utilice descripciones genéricas como "gestionar todo el ciclo de vida de una capacidad". La description debe permitir que el modelo determine de manera estable cuándo seleccionarlo.

2. Determinar los límites de responsabilidad

El cuerpo debe incluir al menos:

Escenarios aplicables y no aplicables;
Objetos que se leen o modifican;
Comportamiento de solo lectura por defecto;
Reglas de confirmación para operaciones de escritura y destructivas;
Pruebas que deben devolverse en caso de fallo.

Un Skill debe organizarse en torno a un límite de capacidad estable. Cuando los requisitos cruzan responsabilidades independientes, debe dividirse en varios Skills.

3. Crear el directorio de código fuente

Los Skills normales de primer nivel y de la comunidad se colocan por defecto en el repositorio agentdock-skills:

skills/<skill-name>/

Solo los Skills principales que están estrechamente vinculados con la versión del runtime de AgentDock y se auto-arrancan con el paquete de instalación se colocan en el repositorio principal de AgentDock:

core-skills/<skill-name>/

Elija la estructura según sea necesario:

skills/<skill-name>/
└── SKILL.md

skills/<skill-name>/
├── SKILL.md
├── references/
├── scripts/
└── tests/

skills/<skill-name>/
├── SKILL.md
├── run.py
└── tests/

No cree directorios vacíos solo por formalismo ni vuelva a colocar integraciones comunes en el repositorio principal de AgentDock.

4. Escribir el Frontmatter

Actualmente, AgentDock analiza oficialmente:

---
name: example-skill
description: Explica claramente cuándo usarlo y qué problema resuelve
version: 1.0.0
---

Requisitos:

name: use un nombre estable, corto, en minúsculas y con guiones;
description: debe cubrir tanto el escenario de activación como el límite de capacidad;
version: use versionado semántico;
Después del frontmatter debe haber un cuerpo Markdown no vacío;
No agregue campos de variables de entorno o ejecución que el analizador actual no soporte.

5. Escribir el núcleo portátil

El cuerpo y los scripts del Skill objetivo asumen por defecto solo:

El directorio de trabajo actual es la raíz del paquete del Skill;
Los recursos dentro del paquete son accesibles mediante rutas relativas;
Las variables de entorno provienen del entorno del proceso actual;
El host en ejecución es responsable de seleccionar herramientas, cambiar directorios e inyectar el entorno;
No dependen del directorio de instalación, el directorio de estado o las variables específicas de AgentDock.

Cuando haya scripts en la raíz, el ejemplo de ejecución general debe escribirse como:

printf '%s' '{"skill_action":"status"}' | python3 run.py

No debe incluir lo siguiente como requisito previo de ejecución principal:

~/.agentdock/skill-store/installed/...;
Un número de versión fijo de instalación;
AGENTDOCK_DIR, AGENTDOCK_HOME o AGENTDOCK_SKILL_DIR para localizar scripts o datos privados dentro del paquete;
skill_env, exec_command o skill://;
Rutas absolutas fijas de usuario;
Leer o source archivos de entorno privados de AgentDock.

Las llamadas a herramientas de AgentDock pueden aparecer en una sección separada de "Adaptación/Verificación de AgentDock", pero después de eliminar esa sección, el Skill debe seguir siendo utilizable.

6. Declarar variables de entorno

Cada Skill objetivo que requiera configuración debe declarar explícitamente las variables en el cuerpo:

## Variables de entorno

| Variable | Tipo | Obligatorio | Descripción |
|---|---:|---|
| EXAMPLE_BASE_URL | config | Sí | Dirección del servicio |
| EXAMPLE_API_KEY | secret | Sí | Clave API |

El tipo debe distinguir al menos entre config y secret, e indicar qué capacidades no están disponibles cuando faltan las variables.

El Skill objetivo solo declara el nombre y el propósito de las variables, no las rutas de almacenamiento privado de AgentDock ni guarda valores reales. Los scripts auxiliares solo leen variables del entorno del proceso actual.

En la verificación local de AgentDock, los valores de entorno se gestionan mediante skill_package env_set/env_unset/env_list y se inyectan en el subproceso hijo por el contexto skill de exec_command. El entorno no se escribe en el proceso principal de AgentDock ni en el entorno del sistema.

7. Escribir materiales de referencia

El contenido adecuado para references/ incluye:

Descripciones de protocolos estables;
Listas de verificación largas;
Tablas de campos de API o códigos de error;
Materiales de antecedentes que no necesitan cargarse completamente cada vez.

El SKILL.md objetivo usa rutas relativas dentro del paquete, por ejemplo:

references/api.md

No use skill://<name>/... como contrato de referencia principal ni dependa del directorio de instalación de otro Skill. AgentDock puede leer recursos mediante read_file skill://<name>/... al verificar el paquete activo actual.

8. Escribir scripts auxiliares

Los scripts auxiliares son solo recursos opcionales, no el cuerpo del Skill. Cuando se necesiten scripts:

La entrada debe ser un objeto JSON por stdin;
El campo de acción de nivel superior debe usar skill_action de manera uniforme;
Las claves solo se leen del entorno del proceso actual;
No pase secretos a través de argumentos de línea de comandos;
La salida debe ser JSON estructurado;
Los errores deben devolver un code estable y un message legible;
Las comprobaciones de estado deben priorizar la solo lectura;
Las operaciones de escritura deben cumplir con las reglas de confirmación del usuario;
Los registros y errores no deben mostrar secretos;
Los archivos dentro del paquete deben usar rutas relativas o basarse en el directorio del propio script.

Entrada recomendada:

{
  "skill_action": "status"
}

Ejecución general desde la raíz del paquete del Skill:

python3 run.py

En la verificación de AgentDock, use skill: "<skill-name>" en exec_command para vincular el directorio activo actual con el entorno independiente; no analice manualmente el directorio de la versión.

9. Ejecutar lint de portabilidad

El run.py de este Skill proporciona:

status: informa la versión del lint y el número de reglas;
lint: verifica el núcleo portátil y los problemas de vinculación con el host del Skill objetivo.

Ejemplo de entrada:

{
  "skill_action": "lint",
  "source": "/path/to/agentdock-skills/skills/example-skill"
}

El resultado incluye:

portable;
error_count;
warning_count;
Para cada incidencia: code, severity, archivo, número de línea, descripción y sugerencia de corrección.

Son errores: codificar un directorio de versión instalada, depender de variables de directorio específicas de AgentDock, leer archivos de entorno de AgentDock o usar rutas absolutas fijas de usuario. Es una advertencia (warning) si en el SKILL.md objetivo aparecen herramientas o URI específicos de AgentDock; deben confirmarse que solo existen en las instrucciones de adaptación opcionales.

Al ejecutar el lint sobre un directorio instalado, se ignora el archivo .agentdock-install.json generado por el instalador de AgentDock en la raíz del paquete. Este archivo pertenece al recibo de instalación del host, no al contenido del paquete del Skill; los archivos con el mismo nombre que aparezcan en otros directorios dentro del paquete se seguirán escaneando normalmente.

En AgentDock, después de instalar una nueva versión de skill-authoring, se puede ejecutar así:

exec_command
  skill: skill-authoring
  cmd: python3 run.py
  stdin: {"skill_action":"lint","source":"/path/to/source"}

Al crear o modificar un Skill de primer nivel, portable debe ser true; cada advertencia debe corregirse una por una o explicarse por qué pertenece a la adaptación opcional del host.

10. Escribir pruebas

Las pruebas cubren los riesgos reales y deben considerar al menos:

Que el frontmatter y el cuerpo sean analizables;
Fallo claro cuando la entrada no es un objeto JSON;
Fallo claro para una skill_action desconocida;
Cuando falten variables de entorno, solo informar el nombre de la variable, sin filtrar el valor;
Que las comprobaciones de estado de solo lectura no produzcan escritura;
Rechazar acciones destructivas sin confirmación;
Que los registros y errores no contengan secretos;
Que ante la falta de plataforma o dependencias se devuelva información diagnóstica;
Ejecución del paquete desde la raíz usando comandos relativos;
Que los scripts no dependan de directorios privados de AgentDock.

11. Verificación de seguridad y calidad

Antes de enviar, verifique:

No hay contraseñas reales, tokens, cookies, cachés de autenticación o archivos de sesión en el paquete;
No hay .env, caché, bases de datos, capturas de pantalla, archivos descargados ni resultados de ejecución;
No hay __pycache__, *.pyc, node_modules ni artefactos compilados;
No hay rutas absolutas fijas de usuario, enlaces simbólicos ni escapes de ruta;
No hay ejemplos de protocolos de ejecución unificados antiguos, herramientas de entorno antiguas o listas de verificación antiguas;
Los destinos de red, escritura de archivos, eliminación, subida y cambios de permisos están claramente explicados;
La instalación de dependencias no se ejecuta ocultamente.

Prohibido explícitamente generar o restaurar:

agentdock.yaml;
skill_run;
skill_env_manage;
AGENTDOCK_OPERATION;
PLUGIN_* (protocolo antiguo);
Listas de verificación antiguas operation o entrypoint;
Ejecutor de Skills unificado o antiguo Skill Runtime.

El estado privado del dispositivo y los valores de entorno de AgentDock pertenecen solo al host y no deben entrar en el paquete.

12. Incrementar la versión

Solo corregir erratas en el cuerpo sin afectar el juicio de comportamiento: incremento de versión de parche;
Agregar capacidades compatibles, variables, acciones o referencias: incremento de versión menor;
Cambiar el límite de responsabilidad, eliminar capacidades existentes o introducir flujos incompatibles: incremento de versión mayor.

Antes de instalar, compare la versión ya instalada con el nuevo código fuente. No sobrescriba contenido diferente con la misma versión.

13. Verificación e instalación local

Complete al menos:

Verificar el directorio y el frontmatter;
Verificar que la versión se haya incrementado correctamente;
Verificar que no haya archivos prohibidos, enlaces simbólicos ni secretos reales;
Realizar un análisis sintáctico de los scripts auxiliares y ejecutar sus pruebas incorporadas;
Ejecutar skill-authoring lint, confirmar que portable=true y revisar las advertencias;
Usar skill_package validate para verificar la validez a nivel de paquete;
Usar skill_package install para instalar y activar;
Verificar a través de agentdock_context que el nombre y la descripción entren en el índice ligero;
Verificar el cuerpo activo actual mediante read_file skill://<name>/SKILL.md;
Si hay referencias, leer al menos una;
Si hay scripts auxiliares, ejecutar status de solo lectura en la versión activa actual con exec_command skill=<name>;
Ejecutar una acción representativa de bajo riesgo; si no se puede ejecutar, registrar el motivo real.

skill_package validate se encarga de si el paquete se puede instalar legalmente; el lint de este Skill se encarga de la calidad de creación y portabilidad de los Skills de primer nivel; no se pueden reemplazar mutuamente.

Variables de entorno

Este Skill en sí mismo no necesita variables de entorno. Requiere que el Skill objetivo que se está escribiendo declare las variables de negocio y que el host en ejecución las inyecte en el subproceso actual.

Criterios de finalización

Solo se considera completado cuando se cumplen simultáneamente las siguientes condiciones:

La descripción se activa de manera estable y el límite está claro;
El núcleo portátil no depende de directorios privados o parámetros de herramientas específicos de AgentDock;
Los scripts dentro del paquete pueden ejecutarse desde la raíz del Skill usando rutas relativas;
skill-authoring lint devuelve portable=true y las advertencias se han gestionado una por una;
Las comprobaciones de seguridad, las pruebas y skill_package validate pasan;
La nueva versión está instalada y activada;
agentdock_context y las lecturas mediante skill:// corresponden a la nueva versión;
La verificación real de solo lectura de la versión activa actual pasa;
No hay secretos, estado privado del dispositivo ni arquitectura antigua en el paquete.

uvwt/agentdock

¿Qué es agentdock?

Preguntar en tu IA favorita

Documentación