zhangliang0115/ai-plugin

Cómo crear una habilidad SKILL.md para múltiples agentes

Una habilidad es una carpeta que contiene un archivo SKILL.md. El archivo comienza con un bloque YAML de metadatos (nombre + descripción) seguido de instrucciones en Markdown que el agente carga bajo demanda. Dado que Claude Code, DeepSeek Harness (dsh), Codex CLI, Gemini CLI, Copilot y Cursor leen este mismo formato, una habilidad bien redactada sirve para todos los agentes.

Anatomía

mi-habilidad/
├── SKILL.md            # requerido: metadatos + instrucciones
├── references/         # opcional: documentación extensa que el modelo lee bajo demanda
└── scripts/            # opcional: scripts auxiliares que la habilidad puede ejecutar

---
name: mi-habilidad
description: >-
  Una o dos frases: qué hace Y cuándo usarla. Es el disparador que el agente
  compara con la solicitud del usuario — escríbelo como una regla de enrutamiento.
---

# Mi habilidad

Instrucciones paso a paso. Asume un ingeniero competente; sé concreto, no vago.

Reglas que determinan si una habilidad funciona

1. name debe estar en kebab-case — letras minúsculas, dígitos, guiones; máximo 64 caracteres. Los agentes rechazan o distorsionan otros nombres. aipx normaliza por ti, pero entrégala correcta.
2. La description es el disparador, no la documentación. Malo: "Utilidades para trabajar con cosas." Bueno: "Resume videos de YouTube/Bilibili y podcasts a partir de una URL. Úsalo cuando el usuario pegue un enlace de video o audio."
3. Mantén SKILL.md por debajo de ~500 líneas. Coloca la profundidad en references/*.md y enlázalos ("ver references/schema.md"). Los agentes cargan el cuerpo solo cuando se activa la habilidad; los cuerpos enormes desperdician contexto y diluyen el comportamiento.
4. Sin habilidades anidadas. El descubrimiento escanea solo los hijos directos de una raíz de habilidad — se encuentra skills/a/SKILL.md, pero no skills/a/b/SKILL.md.
5. Los enlaces relativos deben permanecer relativos. Si SKILL.md referencia scripts/x.py, toda la carpeta viaja junta — nunca enlaces fuera del directorio de la habilidad.

Dónde residen las habilidades (raíces de usuario)

Raíz	Leído por
~/.agents/skills/<nombre>/SKILL.md	DeepSeek Harness (dsh), Codex CLI
~/.claude/skills/<nombre>/SKILL.md	Claude Code
~/.gemini/skills/<nombre>/SKILL.md	Gemini CLI
~/.copilot/skills/<nombre>/SKILL.md	GitHub Copilot CLI

También existen equivalentes con ámbito de proyecto (por ejemplo, .claude/skills/, .agents/skills/ en el repositorio). No copies manualmente — usa aipx sync para enlazar una copia en cada raíz de agente.

Prueba antes de publicar

# ¿Se analiza y descubre?
aipx install ./mi-habilidad --dry-run
aipx install ./mi-habilidad
aipx list

Luego abre tu agente y confirma que la habilidad aparece (Claude Code: aparece en la lista de habilidades; dsh: paleta de comandos / → grupo Skills).

Lista de verificación para publicación

• El repositorio contiene la carpeta de la habilidad en una ruta estable, por ejemplo, skills/mi-habilidad/
• La description indica las condiciones de disparo, no solo las características
• Funciona desde una instalación limpia (aipx install owner/repo#path:/skills/mi-habilidad)
• Agrega temas de GitHub para que el descubrimiento funcione: agent-skills, claude-code, dsh-plugin (si también incluye un paquete dsh), deepseek (si está relacionado con DS)
• Opcional: empaquetado de doble destino — consulta las habilidades dsh-plugin-dev y claude-plugin-dev