make-skill

make-skill — Crie, Adapte e Publique Skills do Jeito Certo

Copie de um repositório de trabalho (geralmente ~/DATA/<nome>): ssheleg/super-ux (suíte multi-skill, regras do Cursor) ou ssheleg/task-pipeline (orquestrador de skill única, automação de release). O próprio make-skill é construído segundo este padrão.

Referências — carregue sob demanda

Leia	Quando
references/agent-skills-spec.md	ao criar ou auditar QUALQUER SKILL.md — limites rígidos de ambas as autoridades, campos opcionais, orçamentos, quem rejeita o quê
references/authoring.md	ao escrever ou ajustar um corpo/descrição — nomenclatura, terceira pessoa, graus de liberdade, regras de script, loops de avaliação
references/surfaces.md	ao publicar em qualquer lugar exceto Claude Code — upload da Skills API/versões/8 por requisição, zip do claude.ai, limites sem rede
references/enterprise.md	ao instalar a skill de outra pessoa, ou governar um parque — tiers de risco, checklist de revisão, portas de aprovação, ciclo de vida
references/retrofit.md	ao auditar uma skill/repositório existente — a checklist de 14 itens, as regras de evidência, o formulário curto de skill pessoal
references/host-capabilities.md	ao publicar um hook, subagente, comando, script ou dependência MCP — o que cada um compra e custa, eventos de hook e códigos de saída, as cláusulas de degradação
references/claude-code-plugin.md	ao publicar qualquer coisa como plugin/marketplace do Claude Code — esquemas de manifesto, layout de componentes, variáveis de caminho, falhas de validate
references/distribution.md	ao layout do repositório, releases e todos os cinco canais — plugin, CLI de skills, npx, Cursor, repositório família guarda-chuva
references/mcp.md, references/mcp-ship.md	skill vs. servidor MCP, encapsulando um — então publicando: montagem, seu 404, server.json, o registro
references/a2a.md	a skill abrange dois agentes autônomos (A2A): Agent Cards, ciclo de vida de tarefas, delegação

Faltando esta cópia? Fallback bruto: raw.githubusercontent.com/ssheleg/make-skill/main/plugins/make-skill/skills/make-skill/references/<arquivo>

Escolhendo um fluxo de trabalho

Detecte a partir da solicitação e de qualquer caminho em $ARGUMENTS; anuncie a escolha.

Situação	Fluxo de trabalho
Nova skill, apenas para os agentes deste usuário	Criar (pessoal)
Nova skill, instalável por outros/outros agentes	Criar (distribuível)
Skill ou repositório existente abaixo deste padrão, "isto corresponde à especificação?"	Retrofit
Skill pessoal deve se tornar instalável	Promover

Sem argumento, detecte em vez de perguntar: um SKILL.md, .claude-plugin/ ou plugins/*/skills/*/ no diretório atual → execute a auditoria Retrofit e relate a tabela de lacunas mais UMA próxima ação. Nada a detectar → pergunte em uma linha o que criar.

Trabalho distribuível é um projeto real: especificação (docs/superpowers/specs/) antes do código, e a especificação trava os contratos de arquivo do projeto-alvo PRIMEIRO — skills são escritas contra esse contrato, nunca ad hoc.

Regras de autoria (todo fluxo de trabalho)

Piso da especificação primeiro — o padrão aberto e as regras de plataforma da Anthropic são ambos inegociáveis; este padrão apenas adiciona em cima. Tabelas de campos, suas diferenças e a checklist: references/agent-skills-spec.md.

• name: regras de caracteres em references/agent-skills-spec.md; igual ao nome do diretório. A armadilha: nunca contém anthropic ou claude — substrings reservadas que o Claude Code carrega feliz e a Skills API rejeita no upload, então a falha aparece na máquina de outra pessoa.
• description: ≤1024 caracteres (o limite é apenas neste campo, não em todo o bloco de front-matter), sem colchetes angulares, terceira pessoa — é injetado no prompt do sistema, onde "Eu posso ajudá-lo…" degrada a seleção. Declare O QUE faz e QUANDO usá-lo.
• O conjunto opcional portátil é license, compatibility, metadata e allowed-tools — limites e tipos em references/agent-skills-spec.md.
• license é opcional — declare-o mesmo assim, no front-matter E na entrada marketplace.json do plugin: um arquivo LICENSE raiz não alcança nem a listagem do plugin nem uma skill instalada, e nada gera erro, então a lacuna permanece (todos os seis repositórios aqui, 2026-07-30).
• Extensões de host são legais, nunca essenciais. O Claude Code lê um conjunto adicional apenas para host (references/claude-code-plugin.md); outros agentes o ignoram, então uma skill DEPENDENDO de uma está quebrada em todos os outros lugares. Fora de spec ∪ host = erro de digitação.
• Corpo < 500 linhas e < 5000 tokens, e mantenha 5% de margem — um corpo em 99% do orçamento transforma a próxima correção em uma briga com o validador. Material mais pesado vai para references/, scripts/, assets/ DENTRO do diretório da skill, um nível de profundidade, cada um vinculado a partir do corpo com um gatilho de carga declarado ("leia X quando Y") — nunca um "veja references/" simples. Arquivos de referência >100 linhas abrem com uma lista ## Conteúdo: uma leitura parcial de head é o que os agentes obtêm.
• Pegadinhas permanecem no SKILL.md: o agente não pode saber que deve abrir um arquivo sobre uma armadilha que ele não sabe que existe.
• Escreva para a superfície mais fraca que você reivindica (references/surfaces.md): o contêiner da API Claude NÃO tem rede e NÃO tem instalação de pacotes, claude.ai varia, apenas o Claude Code tem ambos. Um script que faz pip install ou curl é uma skill do Claude Code — diga isso em compatibility ou remova-o. Nada sincroniza entre superfícies; git é a fonte da verdade.

Acréscimos da casa sobre a especificação:

• Prosa é em Inglês; um literal permanece no idioma em que foi digitado. O Cirílico sobrevive em apenas quatro lugares, onde a string em si é o ponto: uma frase de gatilho, uma frase de recusa (o operador digita ambas — traduzidas, elas não correspondem mais ao que foi dito), um nome próprio, um exemplo de idioma («вы»/«ты»). Uma regra de orçamento precede uma de estilo: o Russo codifica em 1,9–2,3 caracteres/token contra 5,0 do Inglês (cl100k), e reescrever os oito roteadores do ssheleg para Inglês os reduziu 3408 → 1885 tokens sem perda de significado.
• description começa com "Use quando …" e lista frases de gatilho concretas — em Inglês E Russo (o usuário trabalha em ambos). Uma skill que ninguém aciona é peso morto. Mantenha 5% de margem aqui também (≤970 de 1024): um vizinho próximo força uma cláusula "NÃO para …", e uma descrição em 98% do limite não tem onde colocá-la.
• Um padrão de nomenclatura, de preferência gerúndio (processing-pdfs); nunca helper, utils, tools, data — nomes vagos perdem todas as seleções.
• Uma skill = um trabalho. Múltiplas preocupações → múltiplas skills + um arquivo de contrato compartilhado. Coloque os contratos DENTRO do diretório da skill (references/…): a CLI de skills envia apenas o diretório PRÓPRIO da skill, então um skills/references/ IRMÃO funciona como um plugin do Claude Code e chega quebrado em todos os outros agentes. Compartilhado entre skills → duplicado por diretório de skill, verificado como idêntico pelo validador.
• Corpo: imperativo, processual, checklists em vez de prosa; itens inegociáveis declarados como tal. Combine prescritividade com fragilidade — comandos exatos para trabalho destrutivo ou dependente de ordem, direção apenas onde o contexto decide (references/authoring.md).
• Avaliações antes da prosa: execute a tarefa alvo SEM skill, registre as falhas, escreva ≥3 avaliações contra elas, depois escreva o mínimo que passa; uma skill construída sem uma linha de base documenta problemas imaginados. Adicionar a uma família existente → meça a coexistência contra o conjunto INSTALADO, não adivinhe: o vizinho que você nomearia geralmente não é o mais próximo.
• Publique um ponto de entrada de comando único: idempotente — inspecione o estado → repare peças faltantes → relatório de status → exatamente UMA próxima ação sugerida. Modo detecção, nunca pergunte. A skill É esse comando; a invocação difere por canal (/<skill> de um diretório de skills, /<plugin>:<skill> como um plugin) — escreva ambos no README em vez de prometer um.
• Nunca sobrescreva dados do usuário: faça seed apenas quando ausente; sobrescreva apenas atrás de --force.

Contrato de degradação (toda skill que toca uma capacidade do host)

Hooks, subagentes, /commands, variáveis de caminho de plugin e servidores MCP existem apenas dentro do Claude Code — uma minoria de onde as skills são executadas. Cada um é um acelerador com um fallback escrito; a skill ainda conclui seu trabalho sem ele, mas mais lentamente. Escreva os três casos no corpo, nas palavras do agente, no ponto em que ele precisará deles (formatos: references/host-capabilities.md):

• Não é Claude Code (Cursor, Codex, CLI de skills, API): sem hooks, sem subagentes, sem /command. Nomeie o procedimento embutido; scripts/ agrupados ainda viajam, então dê o caminho por canal.
• Plugin/skill recomendado ausente: diga uma vez o que está degradado, continue no caminho manual. Um estágio que se recusa a iniciar porque um companheiro opcional está faltando está quebrado, não é rigoroso.
• Ferramenta, interpretador ou servidor MCP ausente: declare uma vez, recorra ao procedimento manual, nunca tente novamente em um loop. Autenticação interativa é uma etapa humana.

Um fallback que você conhece, mas não escreveu, não é um fallback.

Exemplos de trabalho que esta skill publica — copie estes, não sua memória

scripts/audit_skill.py audita QUALQUER diretório de skill (stdlib; a metade mecânica de um Retrofit), encapsulado como bin/make-skill-audit para Claude Code. Ao lado deles: hooks/ (PostToolUse, silencioso a menos que um SKILL.md tenha sido escrito), commands/skill-audit.md (deliberadamente NÃO o nome da skill), agents/skill-auditor.md, e seis skeletons: assets/SKILL.template.md, assets/plugin.template.json, assets/marketplace.template.json, assets/hooks.template.json, assets/agent.template.md, assets/command.template.md.

Criar (pessoal)

~/.claude/skills/<nome>/SKILL.md conforme as regras de autoria — pronto. Sem repositório, sem versionamento; carrega na próxima sessão. Mencione Promover como o caminho de upgrade.

Precisa de hooks, um agente ou um servidor MCP, ainda sem repositório? Adicione .claude-plugin/plugin.json na mesma pasta — o Claude Code o carrega como <nome>@skills-dir na próxima sessão.

Criar (distribuível)

A árvore de repositório, o piso do repositório público, ambas as execuções de claude plugin validate … --strict e a especificação do validador da casa estão em references/distribution.md → O layout do repositório distributível. Abra-o antes do primeiro arquivo. O que vale independentemente:

• .claude-plugin/marketplace.json na raiz do repositório; o plugin em plugins/<nome>/ com seu próprio .claude-plugin/plugin.json; a skill em plugins/<nome>/skills/<skill>/ com references/, scripts/, assets/ DENTRO dela. Apenas manifestos vivem em .claude-plugin/ — componentes enterrados lá carregam como nada enquanto o plugin ainda parece funcionar.
• Sincronização de versão (regra rígida): marketplace.json, plugin.json, package.json e a entrada principal do CHANGELOG carregam o MESMO semver, incrementados juntos (+ um 5º ponto se SKILL.md carregar metadata.version).
• Ambas as execuções --strict verdes, em CI, como seu próprio job — elas leem MANIFESTOS apenas, então as regras de front-matter vivem em seu próprio test/validate.py, que precisa de um auto-teste negativo: um validador que não pode falhar é decoração. Publique $schema e displayName em plugin.json E na entrada do marketplace (a raiz do marketplace não aceita nenhum dos dois).
• Um repositório público deve ao leitor um README primeiro em Inglês, CONTRIBUTING.md com os comandos offline que verificam uma alteração, e SECURITY.md nomeando um canal privado e o que os instaladores tocam.

Primeira publicação — ponta a ponta, mesma sessão

Leve TUDO até o fim, sem entregas parciais. Apenas a primeira publicação precisa de um humano (npm 2FA); armar a publicação via CI é parte da publicação, então a segunda não precisa. A sequência de 11 etapas está em references/distribution.md → Primeira publicação. Pronto = cinco fatos VERIFICADOS: repositório + CI verde, npm resolvível via npx, plugin instalado, descoberta da CLI de skills funcionando, próxima tag publicada sem um humano.

Retrofit (trazer uma skill/repositório existente para o padrão)

Audite primeiro, corrija depois, na mesma sessão. Veredito por item: PASS / GAP / NOT-RUN com evidência — um file:line ou a saída do comando que você realmente executou. "Parece bom" não é um veredito, e também não é um PASS em uma verificação que foi raciocinada em vez de executada; uma verificação cuja ferramenta está ausente é NOT-RUN com o motivo, nunca um PASS.

Execute o auditor agrupado primeiro — ele faz a metade mecânica deterministicamente, e nunca depende de uma variável não definida:

make-skill-audit <skill-dir> --house    # Claude Code: o bin/ do plugin está no PATH

Em qualquer outro lugar, execute scripts/audit_skill.py do diretório make-skill que você acabou de ler isto. Depois, trabalhe a checklist de 14 itens em references/retrofit.md — piso da especificação, piso do plugin, superfícies, um-trabalho, ponto de entrada, layout e sincronização de versão, validador e CI, avaliações, README, distribuição, meta do repositório, pegadinhas, protocolos, capacidades do host. Para uma skill PESSOAL, apenas três itens se aplicam; esse arquivo diz quais.

Então: relate a tabela de lacunas, corrija tudo que for corrigível agora, suba uma versão minor/patch, execute a checklist de release.

Promover (pessoal → distributível)

Crie o repositório conforme o layout, mova a skill para plugins/<nome>/skills/<skill>/, extraia contratos para references/, depois execute a Primeira publicação ponta a ponta. Exclua a cópia antiga ~/.claude/skills/<skill> apenas APÓS a instalação do plugin ser verificada.

Instalando a skill de outra pessoa

Uma skill são instruções que um agente executa mais código que ele executa sem ler — instalar uma é instalar software. Qualquer coisa que você não escreveu recebe a checklist de revisão em references/enterprise.md PRIMEIRO. Forma de maior risco: uma skill que busca suas instruções de uma URL — esse conteúdo muda após a revisão que o aprovou.

Skills conectadas a protocolos (MCP / A2A)

Uma skill são instruções; ela não pode conceder capacidade. Ensinar o agente COMO é uma skill. Nova capacidade contra um sistema ativo é um servidor MCP (mcp.md, depois mcp-ship.md para montá-lo e publicá-lo). Delegar um resultado para outro agente autônomo é A2A (a2a.md). Ambas as referências carregam as regras de nível de fio — descoberta de nome de ferramenta por host, Agent Cards e autenticação interativa como uma etapa humana.