ssheleg/make-skill

make-skill — Crea, Adapta y Distribuye Habilidades de Forma Probada

Copia desde un repositorio de trabajo (normalmente ~/DATA/<nombre>): ssheleg/super-ux (conjunto de habilidades múltiple, reglas de Cursor) o ssheleg/task-pipeline (orquestador de una sola habilidad, automatización de lanzamientos). make-skill en sí mismo está construido según este canon.

Referencias — carga bajo demanda

Lee	Cuándo
references/agent-skills-spec.md	al crear o auditar CUALQUIER SKILL.md — límites estrictos de ambas autoridades, campos opcionales, presupuestos, quién rechaza qué
references/authoring.md	al escribir o ajustar un cuerpo/descripción — nombres, tercera persona, grados de libertad, reglas de script, bucles de evaluación
references/surfaces.md	al distribuir a cualquier sitio que no sea Claude Code — subida a la API de Skills/versiones/8 por solicitud, zip de claude.ai, los límites sin red
references/enterprise.md	al instalar la habilidad de otra persona, o gobernar un conjunto — niveles de riesgo, lista de verificación de revisión, puertas de aprobación, ciclo de vida
references/retrofit.md	al auditar una habilidad/repositorio existente — la lista de verificación de 14 ítems, las reglas de evidencia, el formulario abreviado de habilidad personal
references/host-capabilities.md	al distribuir un hook, subagente, comando, script o dependencia MCP — qué compra y cuesta cada uno, eventos de hook y códigos de salida, las cláusulas de degradación
references/claude-code-plugin.md	para cualquier cosa que se distribuya como plugin/mercado de Claude Code — esquemas de manifiesto, diseño de componentes, variables de ruta, fallos de validate
references/distribution.md	el diseño del repositorio, lanzamientos, y los cinco canales — plugin, CLI de skills, npx, Cursor, repositorio familiar
references/mcp.md, references/mcp-ship.md	habilidad vs servidor MCP, envolver uno — luego distribuirlo: montaje, su 404, server.json, el registro
references/a2a.md	la habilidad abarca dos agentes autónomos (A2A): Tarjetas de Agente, ciclo de vida de tareas, delegación

¿Falta algo en esta copia? Recurso sin procesar: raw.githubusercontent.com/ssheleg/make-skill/main/plugins/make-skill/skills/make-skill/references/<file>

Elegir un flujo de trabajo

Detectar a partir de la solicitud y cualquier ruta en $ARGUMENTS; anunciar la elección.

Situación	Flujo de trabajo
Nueva habilidad, solo para los agentes de este usuario	Crear (personal)
Nueva habilidad, instalable por otros/otros agentes	Crear (distribuible)
Habilidad o repositorio existente por debajo de este estándar, "¿cumple con la especificación?"	Retrofitting
Habilidad personal debe volverse instalable	Promocionar

Sin argumento, detectar en lugar de preguntar: un SKILL.md, .claude-plugin/ o plugins/*/skills/*/ en el directorio actual → ejecutar la auditoría de Retrofitting e informar la tabla de brechas más UNA siguiente acción. Nada que detectar → preguntar en una línea qué crear.

El trabajo distribuible es un proyecto real: especificación (docs/superpowers/specs/) antes que el código, y la especificación BLOQUEA los contratos de archivo del proyecto objetivo PRIMERO — las habilidades se escriben contra ese contrato, nunca ad hoc.

Reglas de autoría (todos los flujos de trabajo)

Primero el piso de la especificación — el estándar abierto y las reglas de plataforma de Anthropic son ambos no negociables; este canon solo añade encima. Tablas de campos, sus diferencias y la lista de verificación: references/agent-skills-spec.md.

• name: reglas de caracteres en references/agent-skills-spec.md; igual al nombre del directorio. La trampa: nunca contiene anthropic o claude — subcadenas reservadas que Claude Code carga felizmente y la API de Skills rechaza al subir, por lo que el fallo aparece en la máquina de otra persona.
• description: ≤1024 caracteres (el límite está solo en este campo, no en todo el bloque de front-matter), sin ángulos, tercera persona — se inyecta en el prompt del sistema, donde "Puedo ayudarte a…" degrada la selección. Indica QUÉ hace y CUÁNDO usarlo.
• El conjunto opcional portátil es license, compatibility, metadata y allowed-tools — límites y tipos en references/agent-skills-spec.md.
• license es opcional — decláralo de todos modos, en el front matter Y en la entrada del plugin marketplace.json: un archivo LICENSE raíz no llega ni al listado del plugin ni a una habilidad instalada, y nada da error, por lo que la brecha permanece abierta (los seis repositorios aquí, 2026-07-30).
• Las extensiones de anfitrión son legales, nunca críticas. Claude Code lee un conjunto adicional solo del anfitrión (references/claude-code-plugin.md); otros agentes lo ignoran, por lo que una habilidad que DEPENDE de una está rota en cualquier otro lugar. Fuera de la especificación ∪ anfitrión = error tipográfico.
• Cuerpo < 500 líneas y < 5000 tokens, y mantén 5% de margen — un cuerpo al 99% del presupuesto convierte la siguiente corrección en una lucha con el validador. El material más pesado va a references/, scripts/, assets/ DENTRO del directorio de la habilidad, un nivel de profundidad, cada uno enlazado desde el cuerpo con un desencadenante de carga declarado ("lee X cuando Y") — nunca un simple "ver referencias/". Los archivos de referencia de >100 líneas comienzan con una lista ## Contenidos: una lectura parcial con head es lo que obtienen los agentes.
• Las trampas permanecen en SKILL.md: el agente no puede saber que debe abrir un archivo sobre una trampa que no sabe que existe.
• Escribe para la superficie más débil que reclames (references/surfaces.md): el contenedor de la API de Claude NO tiene red y NO tiene instalación de paquetes, claude.ai varía, solo Claude Code tiene ambas. Un script que pip install o curl es una habilidad de Claude Code — dilo en compatibility o elimínalo. Nada se sincroniza entre superficies; git es la fuente de verdad.

Adiciones internas sobre la especificación:

• El texto está en inglés; un literal permanece en el idioma en que está escrito. El cirílico sobrevive solo en cuatro lugares, donde la cadena en sí es el punto: una frase de activación, una frase de rechazo (el operador escribe ambas — traducidas, ya no coinciden con lo dicho), un nombre propio, un ejemplo de idioma («вы»/«ты»). Una regla de presupuesto antes que una de estilo: el ruso codifica a 1.9–2.3 caracteres/token frente a los 5.0 del inglés (cl100k), y reescribir los ocho enrutadores de ssheleg al inglés los redujo 3408 → 1885 tokens sin pérdida de significado.
• description comienza "Usa cuando …" y enumera frases de activación concretas — inglés Y ruso (el usuario trabaja en ambos). Una habilidad que nadie activa es peso muerto. Mantén 5% de margen aquí también (≤970 de 1024): un vecino cercano fuerza una cláusula "NO para …", y una descripción al 98% del límite no tiene dónde ponerla.
• Un patrón de nombre, preferiblemente gerundio (processing-pdfs); nunca helper, utils, tools, data — los nombres vagos pierden toda selección.
• Una habilidad = un trabajo. Múltiples preocupaciones → múltiples habilidades + un archivo de contrato compartido. Pon los contratos DENTRO del directorio de la habilidad (references/…): la CLI de skills envía solo el directorio PROPIO de la habilidad, por lo que un ARCHIVO HERMANO skills/references/ funciona como un plugin de Claude Code y llega roto en cualquier otro agente. Compartido entre habilidades → duplicar por directorio de habilidad, validado por el verificador como idéntico.
• Cuerpo: imperativo, procedimental, listas de verificación sobre prosa; lo no negociable se establece como tal. Iguala la prescriptividad a la fragilidad — comandos exactos para trabajo destructivo o sensible al orden, solo dirección donde el contexto decide (references/authoring.md).
• Evaluaciones antes que prosa: ejecuta la tarea objetivo SIN habilidad, registra los fallos, escribe ≥3 evaluaciones contra ellos, luego escribe el mínimo que pase; una habilidad construida sin una línea base documenta problemas imaginados. Añadir a una familia existente → mide la coexistencia contra el conjunto INSTALADO, no lo adivines: el vecino que nombrarías normalmente no es el más cercano.
• Distribuye un punto de entrada de un solo comando: idempotente — inspeccionar estado → reparar piezas faltantes → informe de estado → exactamente UNA siguiente acción sugerida. Modo de detección, nunca preguntar. La habilidad ES ese comando; la invocación difiere según el canal (/<habilidad> desde un directorio de skills, /<plugin>:<habilidad> como plugin) — escribe ambas en el README en lugar de prometer una.
• Nunca sobrescribas datos del usuario: siembra solo cuando esté ausente; sobrescribe solo detrás de --force.

Contrato de degradación (toda habilidad que toca una capacidad del anfitrión)

Los hooks, subagentes, /commands, variables de ruta de plugins y servidores MCP existen solo en Claude Code — una minoría de donde se ejecutan las habilidades. Cada uno es un acelerador con un plan de contingencia escrito; la habilidad aún termina su trabajo sin él, más despacio. Escribe los tres casos en el cuerpo, en las palabras del agente, en el punto en que los necesitará (formas: references/host-capabilities.md):

• No es Claude Code (Cursor, Codex, CLI de skills, API): sin hooks, sin subagentes, sin /command. Nombra el procedimiento inline; los scripts/ empaquetados aún viajan, así que da la ruta por canal.
• Plugin/habilidad recomendada ausente: di una vez qué está degradado, continúa por la ruta manual. Una etapa que se niega a comenzar porque falta un acompañante opcional está rota, no es estricta.
• Herramienta, intérprete o servidor MCP ausente: indícalo una vez, recurre al procedimiento manual, nunca vuelvas a intentarlo en un bucle. La autenticación interactiva es un paso humano.

Una contingencia que conoces pero no escribiste no es una contingencia.

Ejemplos funcionales que esta habilidad incluye — copia estos, no tu memoria

scripts/audit_skill.py audita CUALQUIER directorio de habilidad (stdlib; la mitad mecánica de un Retrofitting), envuelto como bin/make-skill-audit para Claude Code. Junto a ellos: hooks/ (PostToolUse, silencioso a menos que se haya escrito un SKILL.md), commands/skill-audit.md (DELIBERADAMENTE no el nombre de la habilidad), agents/skill-auditor.md, y seis esqueletos: assets/SKILL.template.md, assets/plugin.template.json, assets/marketplace.template.json, assets/hooks.template.json, assets/agent.template.md, assets/command.template.md.

Crear (personal)

~/.claude/skills/<nombre>/SKILL.md según las reglas de autoría — hecho. Sin repositorio, sin versionado; se carga en la siguiente sesión. Menciona Promocionar como la ruta de actualización.

¿Necesita hooks, un agente o un servidor MCP, aún sin repositorio? Añade .claude-plugin/plugin.json a esa misma carpeta — Claude Code lo carga como <nombre>@skills-dir en la siguiente sesión.

Crear (distribuible)

El árbol del repositorio, el piso de repositorio público, ambas ejecuciones de claude plugin validate … --strict y la especificación del validador interno están en references/distribution.md → El diseño del repositorio distribuible. Ábrelo antes del primer archivo. Lo que se mantiene independientemente:

• .claude-plugin/marketplace.json en la raíz del repositorio; el plugin bajo plugins/<nombre>/ con su propio .claude-plugin/plugin.json; la habilidad en plugins/<nombre>/skills/<habilidad>/ con references/, scripts/, assets/ DENTRO de ella. Solo los manifiestos viven en .claude-plugin/ — los componentes enterrados allí se cargan como nada mientras el plugin aún parece funcionar.
• Sincronización de versión (regla estricta): marketplace.json, plugin.json, package.json y la entrada superior de CHANGELOG llevan la MISMA semver, incrementados juntos (+ un 5º punto si SKILL.md tiene metadata.version).
• Ambas ejecuciones de --strict en verde, en CI, como su propio trabajo — leen solo MANIFIESTOS, por lo que las reglas de front-matter viven en tu propio test/validate.py, que necesita una autoprueba negativa: un validador que no puede fallar es decoración. Incluye $schema y displayName en plugin.json Y en la entrada del mercado (la raíz del mercado no toma ni uno ni otro).
• Un repositorio público le debe al lector un README en inglés primero, CONTRIBUTING.md con los comandos offline que verifican un cambio, y SECURITY.md nombrando un canal privado y qué tocan los instaladores.

Primer lanzamiento — de extremo a extremo, misma sesión

Lleva TODO hasta el final, sin entregas a medias. Solo el primer lanzamiento necesita un humano (2FA de npm); armar la publicación en CI es parte de la distribución, por lo que el segundo no. La secuencia de 11 pasos está en references/distribution.md → Primer lanzamiento. Hecho = cinco HECHOS VERIFICADOS: repositorio + CI en verde, npm resoluble vía npx, plugin instalado, descubrimiento de la CLI de skills funcionando, la siguiente etiqueta publicándose sin un humano.

Retrofitting (llevar una habilidad/repositorio existente al estándar)

Auditar primero, corregir después, en la misma sesión. Veredicto por ítem: PASA / BRECHA / NO-EJECUTADO con evidencia — un archivo:línea o la salida del comando que realmente se ejecutó. "Parece bien" no es un veredicto, y tampoco lo es un PASA en una verificación de la que se razonó en lugar de ejecutarse; una verificación cuya herramienta está ausente es NO-EJECUTADO con la razón, nunca un PASA.

Ejecuta el auditor incluido primero — hace la mitad mecánica de forma determinista, y nunca depende de una variable no establecida:

make-skill-audit <directorio-habilidad> --house    # Claude Code: el bin/ del plugin está en PATH

En cualquier otro lugar, ejecuta scripts/audit_skill.py desde el directorio make-skill que acabas de leer. Luego trabaja la lista de verificación de 14 ítems en references/retrofit.md — piso de especificación, piso de plugin, superficies, un trabajo, punto de entrada, diseño y sincronización de versiones, validador y CI, evaluaciones, README, distribución, meta del repositorio, trampas, protocolos, capacidades del anfitrión. Para una habilidad PERSONAL solo se aplican tres ítems; ese archivo dice cuáles.

Luego: informa la tabla de brechas, corrige todo lo que se pueda corregir ahora, incrementa una versión menor/patch, ejecuta la lista de verificación de lanzamiento.

Promocionar (personal → distribuible)

Crea el repositorio según el diseño, mueve la habilidad a plugins/<nombre>/skills/<habilidad>/, extrae los contratos a references/, luego ejecuta el Primer lanzamiento de extremo a extremo. Elimina la copia antigua de ~/.claude/skills/<habilidad> solo DESPUÉS de que se verifique la instalación del plugin.

Instalar la habilidad de otra persona

Una habilidad son instrucciones que un agente ejecuta más código que ejecuta sin leerlo — instalar una es instalar software. Cualquier cosa que no hayas escrito obtiene la lista de verificación de revisión en references/enterprise.md PRIMERO. La forma de mayor riesgo: una habilidad que obtiene sus instrucciones de una URL — ese contenido cambia después de la revisión que lo aprobó.

Habilidades conectadas por protocolo (MCP / A2A)

Una habilidad son instrucciones; no puede otorgar capacidad. Enseñar al agente CÓMO es una habilidad. Nueva capacidad contra un sistema en vivo es un servidor MCP (mcp.md, luego mcp-ship.md para montarlo y publicarlo). Delegar un resultado a otro agente autónomo es A2A (a2a.md). Ambas referencias llevan las reglas a nivel de cable — descubrimiento de nombres de herramientas por anfitrión, Tarjetas de Agente, y autenticación interactiva como un paso humano en lugar de…