O nome do diretório faz parte do contrato
O campo name do frontmatter precisa coincidir com o nome do diretório pai, então renomear uma skill significa renomear os dois. É a restrição mais quebrada na prática, quase sempre ao copiar uma pasta e editar apenas o arquivo de dentro. A skill então falha na validação ou é ignorada, sem nada na saída explicando o motivo.
Escopo de projeto contra escopo de usuário
Uma skill guardada com um projeto viaja com o repositório, então quem clonar recebe as mesmas instruções e o mesmo histórico de revisão. Uma skill guardada na sua configuração de usuário acompanha você em todos os projetos. Convenções que pertencem a um código ficam com esse código; hábitos que são seus ficam no escopo de usuário.
O que vai nos subdiretórios
SKILL.md guarda o frontmatter e as instruções. scripts/ guarda código executável que o agente pode rodar, references/ guarda documentação carregada só quando a tarefa precisa, e assets/ guarda templates, imagens e arquivos de dados. Mantenha as referências a um nível de profundidade a partir do SKILL.md para o agente não perseguir um caminho em vários saltos.