Skills, scripts, progressive disclosure
Uma skill reúne instruções e recursos para uma tarefa recorrente, carregados conforme a necessidade. Ela difere de um arquivo geral de regras do projeto: seu objetivo é executar um procedimento especializado. Nesta semana você transformará uma rotina de revisão de contratos em um pacote reutilizável.
O caso é verificar schemas de importação de pedidos. A skill precisa reconhecer quando se aplica, orientar inspeção e usar um script local para verificações determinísticas. Seu valor será medido pela qualidade do procedimento e dos artefatos, não pelo número de instruções acumuladas.
JavaScriptProgramaçãoAo terminar esta aula
- Skills especializam rotinas recorrentes.
- Carregamento em camadas reduz contexto desnecessário.
- Recursos e instruções evoluem juntos.
Antes de continuar: Laboratório: Rules, AGENTS.md, CLAUDE.md
Skill e progressive disclosure
FundamentosUma skill possui descrição que ajuda a identificar sua aplicação e um corpo que orienta a execução. Progressive disclosure apresenta informação em camadas: metadados para descoberta, instruções quando a skill é relevante e recursos adicionais apenas quando necessários. Essa organização evita carregar todos os manuais em toda tarefa. A especificação Agent Skills descreve uma estrutura interoperável, mas o produto que a utiliza pode acrescentar regras de instalação, descoberta e permissões. Confira essas regras antes de assumir comportamento uniforme.
Para revisão de contratos, a descrição precisa distinguir entrada e resultado: usar quando um schema ou endpoint de importação muda, para verificar compatibilidade e produzir relatório de discrepâncias. Uma descrição genérica como “melhora código” compete com qualquer tarefa e gera acionamentos inadequados. O corpo deve informar pré-requisitos, sequência, decisões e critérios de conclusão. A skill não cria acesso ao repositório ou serviços; ela utiliza capacidades já autorizadas. Essa fronteira mantém reutilização separada de autoridade.
Instruções, scripts, references e assets
ProgramaçãoO diretório scripts guarda execução automatizável; references guarda documentação consultável; assets guarda materiais usados na saída. Não confunda essas categorias com permissões. Um script pode ter efeitos amplos, portanto precisa de contrato de entrada, saída e ambiente. Para revisão de schema, um script local pode verificar campos obrigatórios e produzir um relatório. O agente interpreta o resultado, mas não deve substituir uma falha determinística por uma explicação otimista.
As referências podem conter exemplos de compatibilidade e regras do domínio, enquanto um asset pode ser um modelo de relatório. Mantenha caminhos relativos corretos e evite depender de um arquivo pessoal fora do pacote. Recursos extensos devem ser consultados quando a etapa exige, não copiados integralmente para o corpo principal. Uma skill sustentável informa por que e quando abrir cada recurso. Também precisa tratar ausência de dependência: instalar algo sem autorização ou continuar como se o script tivesse rodado são respostas inadequadas. O relatório registra o bloqueio e o que foi verificado localmente.
Procedimento reutilizável precisa de decisões
FundamentosUma boa skill não é uma lista de frases vagas. Ela descreve o caminho nominal e bifurcações relevantes. Na revisão de contrato, primeiro identificar versão vigente e consumidores; depois comparar mudanças; então classificar quebra ou adição compatível; por fim verificar exemplos e emitir relatório. Se um campo passa de opcional a obrigatório, a skill deve pedir evidência de migração ou tratamento de consumidores antigos. Essa decisão não depende apenas da forma do JSON.
Separe automação e julgamento. Um script pode detectar remoção de campo; avaliar se isso quebra consumidores exige o contrato e o uso real. O agente deve procurar essa evidência e indicar incerteza quando faltar. Retome a semana de instruções persistentes: coding standards orientam o projeto inteiro, enquanto a skill especializa uma rotina. Não duplique regras gerais extensas dentro de cada pacote. Referencie o contexto apropriado e resolva conflitos segundo o ambiente. A reutilização melhora quando o procedimento possui entradas claras e resultado verificável.
Versionamento, segurança e avaliação
SegurançaAvaliaçãoVersione a skill e seus recursos juntos. Uma mudança no script pode alterar o significado de um relatório, portanto a versão precisa acompanhar a execução. Registre compatibilidade com ferramentas e dependências necessárias, sem presumir que arquivos de lock de outro projeto servem aqui. Revise também o conteúdo de referências: documentação externa pode conter instruções irrelevantes ou não confiáveis, que não devem ampliar permissões. Uma skill instalada é um pacote de orientação e potencial execução, merecendo inspeção antes de uso.
Avalie com casos nominal, quebrado e fora do escopo. No nominal, uma propriedade opcional é acrescentada. No quebrado, um campo obrigatório é removido. Fora do escopo, a tarefa é editar texto de marketing e a skill não deveria disparar. Observe resultados, não apenas a declaração de que o pacote foi carregado. Uma skill que sempre produz “aprovado” falha mesmo se sua descrição for perfeita. A aceitação inclui relatório com evidência, classificação da mudança e limitações. Reutilizar o pacote deve reduzir trabalho repetido sem reduzir rigor.
Exemplo comentado e limites
FundamentosO script compara apenas conjuntos de nomes e não implementa toda a semântica de JSON Schema. A remoção de valor é uma discrepância detectável que precisa de análise do contrato. O relatório inclui a versão do procedimento para rastrear alterações na rotina.
const anterior = {obrigatorios:["id","valor"]};
const novo = {obrigatorios:["id"]};
function comparar(a,b) {
return {removidos:a.obrigatorios.filter(x=>!b.obrigatorios.includes(x)),
adicionados:b.obrigatorios.filter(x=>!a.obrigatorios.includes(x))};
}
console.log({skill:"revisar-contrato",versao:"1",resultado:comparar(anterior,novo)});Remover obrigatoriedade pode tornar a entrada mais permissiva, mas também quebrar código que presume presença do campo. Tornar um campo obrigatório pode rejeitar clientes antigos. Portanto, “removido” não deve ser convertido automaticamente em uma conclusão universal de compatibilidade. A skill precisa examinar a fronteira e os consumidores.
Exercício aplicado
Empacote uma rotina de revisão que detecte remoção de campo obrigatório e não execute em tarefas de marketing.
- Tente a revisão manual e defina saída.
- Organize instruções e recursos por finalidade.
- Execute casos nominal, quebrado e fora do escopo.
- Versione relatório e documente lacunas.
Abrir resolução comentada
A solução separa metadados, instrução, comparação local e relatório. A descrição limita o escopo a mudanças de contrato. O corpo exige consultar consumidores antes de classificar a discrepância e registra quais verificações foram executadas.
Uma avaliação adequada inclui um caso que deve acionar a skill e outro que não deve. O script roda sobre dados fictícios, e a execução externa de um produto só pode ser afirmada quando observada. O relatório final informa compatibilidade, evidência e pendências de migração.
A skill madura detecta discrepâncias, busca evidência de consumidores e registra limitações. O código é apenas uma etapa do procedimento; o pacote não deve confundir execução local com avaliação completa de compatibilidade.
A resolução materializa três pacotes com SKILL.md, scripts, references e assets em diretório temporário e verifica os caminhos. Os três scripts são executados em subprocessos com asserts para mudança de tipo, validação e escopo, e estrutura de rejeições. O relatório separa detecção de julgamento de compatibilidade. Descoberta e acionamento por agente não foram executados; devem ser observados no produto escolhido com os casos fornecidos.
import assert from "node:assert/strict";
import {mkdtempSync,mkdirSync,writeFileSync,existsSync,readFileSync} from "node:fs";
import {tmpdir} from "node:os";import {join} from "node:path";
import {spawnSync} from "node:child_process";
const pasta=mkdtempSync(join(tmpdir(),"curso-skills-"));
const pacotes=[
{nome:"revisar-contrato",descricao:"Use em mudanças de schema de importação para relatar discrepâncias e consumidores afetados.",
passos:"Compare contratos; verifique consumidores; não confunda discrepância com quebra comprovada."},
{nome:"validar-importacao",descricao:"Use para verificar identificador, valor e escopo em dados de importação de pedidos.",
passos:"Execute validação; preserve rejeições e códigos; não exponha linhas sensíveis em logs."},
{nome:"revisar-rejeicoes",descricao:"Use para revisar relatório de linhas rejeitadas e sua utilidade para o operador.",
passos:"Confira linha, código e motivo; relacione requisitos e evidência; reporte lacunas de interface."}
];
for(const pacote of pacotes){const base=join(pasta,pacote.nome);
for(const dir of [base,join(base,"scripts"),join(base,"references"),join(base,"assets")])mkdirSync(dir);
const skill="---\nname: "+pacote.nome+"\ndescription: "+pacote.descricao+"\n---\n\n# Procedimento\n"+
pacote.passos+"\n\nConsulte references/criterios.md; use scripts/validar.mjs para inspeção local; " +
"preencha assets/relatorio.json com versão, evidência e limitações. Fora do escopo: texto de marketing.\n";
writeFileSync(join(base,"SKILL.md"),skill);
const scripts={
"revisar-contrato":"import assert from 'node:assert/strict';const antes={valor:'number'},depois={valor:'string'};const alterados=Object.keys(antes).filter(k=>antes[k]!==depois[k]);assert.deepEqual(alterados,['valor']);console.log(JSON.stringify({versao:1,alterados,julgamento:'consultar consumidores'}));",
"validar-importacao":"import assert from 'node:assert/strict';const validar=(linha,ctx)=>linha.tenant===ctx.tenant&&typeof linha.id==='string'&&linha.id.length>0&&Number.isSafeInteger(linha.valor)&&linha.valor>=0;assert.equal(validar({tenant:'A',id:'p1',valor:10},{tenant:'A'}),true);assert.equal(validar({tenant:'A',id:'p2',valor:-1},{tenant:'A'}),false);assert.equal(validar({tenant:'B',id:'p3',valor:10},{tenant:'A'}),false);console.log(JSON.stringify({versao:1,casos:3,status:'aprovado'}));",
"revisar-rejeicoes":"import assert from 'node:assert/strict';const validar=r=>Number.isSafeInteger(r.linha)&&r.linha>0&&typeof r.codigo==='string'&&r.codigo.length>0&&typeof r.motivo==='string'&&r.motivo.trim().length>0;assert.equal(validar({linha:2,codigo:'VALOR_INVALIDO',motivo:'Valor negativo'}),true);assert.equal(validar({linha:0,codigo:'',motivo:''}),false);console.log(JSON.stringify({versao:1,casos:2,status:'aprovado',conteudoIntegralRegistrado:false}));"
};
writeFileSync(join(base,"scripts","validar.mjs"),scripts[pacote.nome]);
const execucao=spawnSync(process.execPath,[join(base,"scripts","validar.mjs")],{encoding:"utf8"});
assert.equal(execucao.status,0,execucao.stderr);
writeFileSync(join(base,"references","criterios.md"),"# Critérios\nSeparar observação, julgamento e integração pendente.\n");
writeFileSync(join(base,"assets","relatorio.json"),JSON.stringify({skill:pacote.nome,versao:1,evidencias:[],lacunas:[]}));
assert.ok(existsSync(join(base,"scripts","validar.mjs")));
assert.ok(readFileSync(join(base,"SKILL.md"),"utf8").includes("Fora do escopo"));
}
function comparar(a,b){return {removidos:a.obrigatorios.filter(x=>!b.obrigatorios.includes(x)),
adicionados:b.obrigatorios.filter(x=>!a.obrigatorios.includes(x)),
tiposAlterados:Object.keys(a.tipos).filter(x=>b.tipos[x]&&a.tipos[x]!==b.tipos[x])};}
const anterior={obrigatorios:["id","valor"],tipos:{id:"string",valor:"number"}};
const nominal=comparar(anterior,{obrigatorios:["id","valor"],tipos:{...anterior.tipos,nota:"string"}});
const quebrado=comparar(anterior,{obrigatorios:["id"],tipos:{id:"string",valor:"string"}});
assert.equal(nominal.removidos.length,0);assert.deepEqual(quebrado.removidos,["valor"]);
assert.deepEqual(quebrado.tiposAlterados,["valor"]);
const foraEscopo={tarefa:"editar marketing",usarRevisaoContrato:false};assert.equal(foraEscopo.usarRevisaoContrato,false);
const relatorio={versao:1,discrepancias:quebrado,julgamento:"consultar consumidores antes de decidir compatibilidade",
limites:["scripts locais executam asserts; consumidores reais precisam ser inspecionados","descoberta por agente não executada"]};
console.log({status:"aprovado",pasta,pacotes:pacotes.length,nominal,quebrado,foraEscopo,relatorio});Como conferir seu resultado
- Descrição limita acionamento.
- Recursos possuem contratos e caminhos válidos.
- Relatório distingue detecção e julgamento.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Separar metadados/instruções/recursos.
- Distinguir schema e consumidor.
API torna cep obrigatório. Quando skill deve acionar e quais recursos sustentam análise?
Conferir raciocínio e critérios de domínio
Mudança de contrato aciona; marketing não.
Clientes antigos sem cep podem falhar; adicionar obrigatório não é universalmente compatível.
Script detecta mudança; consumidor/migração justificam decisão, recursos carregados por necessidade.
Evidências para autoavaliação ou revisão por pares
- Acionamento: Mudança de contrato aciona; marketing não.
- Compatibilidade: Clientes antigos sem cep podem falhar; adicionar obrigatório não é universalmente compatível.
- Evidência: Script detecta mudança; consumidor/migração justificam decisão, recursos carregados por necessidade.
Um erro frequente
Adicionar campo é sempre compatível.
Adicionar obrigatoriedade pode quebrar consumidores antigos.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Progressive disclosure carrega todo recurso sempre?
2. Uma skill concede permissão de terminal?
3. Comparar nomes prova compatibilidade completa?
Não.
Tipos, semântica e consumidores também influenciam o contrato.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Agent Skills specification
Agent Skills • consulta: 2026-10-06
AgentesSKILL.md, metadata, scripts/references/assets e progressive disclosure.
Limites: Formato interoperável não garante suporte idêntico em cada cliente; pin e revisão da versão da skill são prática editorial.
- Build skills
OpenAI • consulta: 2026-10-06
OpenAICriação, descoberta e uso de skills em ChatGPT/Codex, com recursos complementares.
Limites: Documentação dinâmica; fixar a versão usada no laboratório e conferir compatibilidade antes de executar.
- GitHub Spec Kit
GitHub • consulta: 2026-10-06
FundamentosFluxo requirements → specification → technical plan → tasks → implement/converge; consistência e checklists.
Limites: Ferramenta concreta para ensinar SDD, não padrão universal; comandos atuais podem diferir de tutoriais antigos.
- AIP-180: Backwards compatibility
Google API Improvement Proposals • consulta: 2026-10-06
APIsCompatibilidade de APIs: aspectos de código-fonte, comunicação e semântica; mudanças em campos e comportamento.
Limites: Diretriz de design de APIs Google; não é um teste completo para toda implementação nem garantia de compatibilidade de um projeto.