El nombre del directorio forma parte del contrato
El campo name del frontmatter debe coincidir con el nombre del directorio padre, así que renombrar una skill implica renombrar ambos. Es la restricción que más se rompe, casi siempre al copiar una carpeta y editar solo el archivo de dentro. La skill entonces no pasa la validación o se ignora, sin nada en la salida que explique el motivo.
Alcance de proyecto frente a alcance de usuario
Una skill guardada con un proyecto viaja con el repositorio, así que cualquiera que lo clone recibe las mismas instrucciones y el mismo historial de revisión. Una skill guardada en tu configuración de usuario te acompaña en todos los proyectos. Las convenciones de un código concreto pertenecen a ese código; los hábitos que son tuyos pertenecen al alcance de usuario.
Qué va en los subdirectorios
SKILL.md contiene el frontmatter y las instrucciones. scripts/ guarda código ejecutable que el agente puede correr, references/ guarda documentación que solo se carga cuando la tarea la necesita, y assets/ guarda plantillas, imágenes y archivos de datos. Mantén las referencias a un nivel de profundidad desde SKILL.md para que el agente no tenga que perseguir una ruta en varios saltos.