Formato de Skill

En disco

Un Skill es una carpeta.

Obligatorio:

• SKILL.md (o skill.md; también se acepta el heredado skills.md)

Opcional:

• cualquier archivo basado en texto de apoyo (consulta “Archivos permitidos”)
• .clawhubignore (patrones de exclusión para publicación, heredado .clawdhubignore)
• .gitignore (también se respeta)

Importación desde GitHub

El importador web de GitHub es más estricto que la publicación/sincronización local. Solo detecta archivos SKILL.md o heredados skills.md en repositorios públicos, que no sean forks, propiedad de la cuenta de GitHub con sesión iniciada. No importa repositorios privados, forks, repositorios archivados/deshabilitados ni repositorios públicos de terceros.

Metadatos de instalación local (escritos por la CLI):

• <skill>/.clawhub/origin.json (heredado .clawdhub)

Estado de instalación del directorio de trabajo (escrito por la CLI):

• <workdir>/.clawhub/lock.json (heredado .clawdhub)

SKILL.md

• Markdown con frontmatter YAML opcional.
• El servidor extrae metadatos del frontmatter durante la publicación.
• description se usa como resumen del Skill en la interfaz de usuario/búsqueda.

Metadatos de frontmatter

Los metadatos del Skill se declaran en el frontmatter YAML en la parte superior de tu SKILL.md. Esto indica al registro (y al análisis de seguridad) qué necesita tu Skill para ejecutarse.

Frontmatter básico

---name: my-skilldescription: Short summary of what this skill does.version: 1.0.0---

Metadatos de runtime (metadata.openclaw)

Declara los requisitos de runtime de tu Skill en metadata.openclaw (alias: metadata.clawdbot, metadata.clawdis).

---name: my-skilldescription: Manage tasks via the Todoist API.metadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY---

Usa requires.env para variables de entorno que deben estar presentes antes de que el Skill pueda ejecutarse. Usa envVars cuando necesites metadatos por variable, incluidas variables opcionales con required: false.

Referencia completa de campos

Especificaciones de instalación

Si tu Skill necesita dependencias instaladas, decláralas en el arreglo install:

metadata:  openclaw:    install:      - kind: brew        formula: jq        bins: [jq]      - kind: node        package: typescript        bins: [tsc]

Tipos de instalación compatibles: brew, node, go, uv.

Variables de entorno opcionales

Declara variables de entorno opcionales en metadata.openclaw.envVars y define required: false. No agregues entradas opcionales a requires.env, porque requires.env significa que el Skill no puede ejecutarse sin ellas.

metadata:  openclaw:    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: Todoist API token used for authenticated requests.      - name: TODOIST_PROJECT_ID        required: false        description: Optional default project ID when the user does not specify one.

Por qué esto importa

El análisis de seguridad de ClawHub comprueba que lo que declara tu Skill coincida con lo que realmente hace. Si tu código referencia TODOIST_API_KEY pero tu frontmatter no lo declara en requires.env, primaryEnv o envVars, el análisis marcará una discrepancia de metadatos. Mantener declaraciones precisas ayuda a que tu Skill pase la revisión y ayuda a los usuarios a entender qué están instalando.

Ejemplo: frontmatter completo

---name: todoist-clidescription: Manage Todoist tasks, projects, and labels from the command line.version: 1.2.0metadata:  openclaw:    requires:      env:        - TODOIST_API_KEY      bins:        - curl    primaryEnv: TODOIST_API_KEY    envVars:      - name: TODOIST_API_KEY        required: true        description: Todoist API token.      - name: TODOIST_PROJECT_ID        required: false        description: Optional default project ID.    emoji: "\u2705"    homepage: https://github.com/example/todoist-cli---

Archivos permitidos

La publicación solo acepta archivos “basados en texto”.

• La lista de extensiones permitidas está en packages/schema/src/textFiles.ts (TEXT_FILE_EXTENSIONS).
• Los archivos de script se siguen escaneando después de la carga; los archivos de PowerShell .ps1, .psm1 y .psd1 se aceptan como texto.
• Los tipos de contenido que empiezan con text/ se tratan como texto; además de una pequeña lista permitida (JSON/YAML/TOML/JS/TS/Markdown/SVG).

Límites (del lado del servidor):

• Tamaño total del paquete: 50 MB.
• El texto de embedding incluye SKILL.md + hasta aproximadamente 40 archivos que no sean .md (límite de mejor esfuerzo).

Slugs

• Se derivan del nombre de carpeta de forma predeterminada.
• Los scopes de paquete deben coincidir exactamente con el identificador del publicador de ClawHub. Los identificadores de publicador pueden usar letras minúsculas, números, guiones, puntos y guiones bajos; deben empezar y terminar con una letra minúscula o un número.
• Los slugs de paquete deben estar en minúsculas y ser seguros para npm, por ejemplo @example.tools/demo-plugin o demo-plugin.

Versionado + etiquetas

• Cada publicación crea una nueva versión (semver).
• Las etiquetas son punteros de cadena a una versión; latest se usa habitualmente.

Licencia

• Todos los Skills publicados en ClawHub tienen licencia MIT-0.
• Cualquiera puede usar, modificar y redistribuir Skills publicados, incluso comercialmente.
• No se requiere atribución.
• No agregues términos de licencia contradictorios en SKILL.md; ClawHub no admite sobrescrituras de licencia por Skill.

Skills de pago

• ClawHub no admite Skills de pago, precios por Skill, paywalls ni reparto de ingresos.
• No agregues metadatos de precios a SKILL.md; no forman parte del formato de Skill y no harán que un Skill publicado sea de pago.
• Si tu Skill se integra con un servicio de terceros de pago, documenta claramente el costo externo y la cuenta requerida en las instrucciones del Skill y en las declaraciones de entorno (requires.env para variables obligatorias, o envVars con required: false para variables opcionales).