Skills, scripts, progressive disclosure
O laboratório transforma uma revisão pontual em procedimento reutilizável. Você escreverá descrição de acionamento, instruções e um recurso executável, mantendo o julgamento de compatibilidade separado da detecção mecânica. A entrega inclui casos para avaliar o pacote.
Use diretório de prática e arquivos fictícios. Escolha um produto-alvo somente para conferir sua descoberta de skills. Se não houver acesso, valide o pacote local e declare a integração pendente. Nenhuma etapa deve instalar ou executar recurso desconhecido por hábito.
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: Leitura: Skills, scripts, progressive disclosure
Definir escopo e tentar a revisão
FundamentosCompare os dois contratos manualmente antes de executar o script. Escreva a discrepância e a pergunta sobre consumidores que impede uma conclusão automática. Depois redija uma descrição que mencione mudanças de schema e relatório de compatibilidade. Inclua exemplos de tarefas fora do escopo. Essa preparação retoma o uso de contratos da semana anterior e impede que a skill vire uma rotina genérica aplicada a qualquer código. Defina também o que significa terminar: relatório com evidência e pendências, não apenas execução de um comando.
Organizar o pacote
FundamentosCrie o arquivo principal com etapas, pré-requisitos e critérios. Coloque a comparação em scripts e exemplos de classificação em references. Se usar um modelo de relatório, guarde em assets e explique quando copiá-lo. Confira todos os caminhos a partir do diretório da skill. Documente a versão de runtime necessária e o comportamento quando estiver ausente. Um recurso não encontrado deve gerar uma limitação explícita. Evite copiar instruções gerais do repositório para o pacote; consulte-as quando a tarefa ocorrer em um projeto real.
Executar casos de avaliação
AvaliaçãoRode remoção, adição e contratos iguais. Compare o relatório com seu julgamento manual. Acrescente mudança de tipo para mostrar que o script simples ainda não cobre tudo. A skill deve indicar a lacuna, não emitir uma aprovação automática. Em uma ferramenta com descoberta disponível, teste um pedido pertinente e outro fora do escopo. Registre acionamento observado e resultado. O teste de comportamento importa mais que a capacidade do agente de recitar o nome do pacote.
Versionar e revisar a manutenção
FundamentosInclua versão no relatório e revise mudanças do script junto das instruções. Faça uma alteração deliberada no formato de saída para perceber o impacto sobre consumidores. Defina como evoluir o procedimento sem invalidar relatórios antigos silenciosamente. Compare o compromisso entre instrução extensa e referências consultáveis: o corpo precisa orientar o caminho, mas detalhes longos podem ser carregados só na etapa pertinente. Finalize com documentação de instalação do produto-alvo, limitações locais e casos de avaliação preservados para futuras revisões.
Completar o kit com três skills
FundamentosO kit da fase possui três procedimentos complementares: revisar contrato, validar dados de importação e revisar relatório de rejeições. A primeira compara estruturas e consumidores; a segunda executa regras de identificador, valor e escopo; a terceira verifica se cada rejeição contém número, código e mensagem útil sem exposição indevida. Escreva uma descrição e um arquivo principal para cada pacote, evitando acionamento simultâneo indiscriminado. Reuse scripts apenas com contratos claros e versionados. Avalie tarefas pertinentes e fora do escopo de cada skill. O AGENTS.md da semana anterior mantém comandos e arquitetura gerais, enquanto as skills carregam detalhe especializado. O kit está completo quando um agente novo consegue descobrir o procedimento adequado e produzir evidência verificável, com falhas e dependências ausentes declaradas.
↗ Agent Skills specification↗ Custom instructions with AGENTS.md
Caso adicional para diagnóstico e decisão
FundamentosAdicione uma dependência ausente ao script de validação e observe o comportamento do procedimento. A skill deve identificar pré-requisito, informar a lacuna e continuar somente nas partes independentes que realmente pode verificar. Não deve declarar aprovação do script nem instalar software automaticamente fora do escopo. Escreva um relatório parcial que diferencie inspeção, execução e resultado. Em seguida, mude o formato de saída do script sem atualizar a referência. O teste do pacote deve detectar essa incompatibilidade. A rubrica adicional exige caminhos válidos, contratos entre recursos e honestidade sobre execução. Compare duplicar a mesma documentação nos três pacotes com uma referência compartilhada versionada. A referência reduz divergência, mas cria dependência que precisa ser distribuída e mantida. Escolha conforme a forma de instalação do produto-alvo e registre como a avaliação encontrará uma versão antiga.
Execução, inspeção e diagnóstico
FundamentosExecute a comparação e confira os conjuntos. Acrescente um contrato em que valor muda de número para string e observe que o script não detecta a semântica. Use essa falha para acrescentar uma etapa explícita de inspeção de tipos na skill.
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)});Se o pacote dispara em marketing, a descrição está ampla ou o produto interpretou seu escopo de outra forma. Se o relatório aprova mudança de tipo, a rotina de julgamento está incompleta. Se o script não foi executado, não atribua seu resultado à ferramenta. Registre a causa concreta.
Exercício aplicado
Entregue uma skill de revisão de contratos com recursos, versão e avaliação de acionamento.
- 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.
Empacote cep opcional→obrigatório e teste schema/marketing/script ausente.
Conferir raciocínio e critérios de domínio
A tarefa de alterar cep aciona a skill; marketing não. Um acionamento em marketing é falso positivo, não aprovação da qualidade do pacote.
Tornar cep obrigatório rejeita a entrada antiga sem cep; o relatório classifica a mudança como quebradora para esse consumidor e aponta migração/compatibilidade necessária.
Quando o script está ausente, o resultado é bloqueio de execução com inspeção manual declarada. Não aparece 'script passou'; instruções, recursos e versão permanecem identificados.
Evidências para autoavaliação ou revisão por pares
- Acionamento: A tarefa de alterar cep aciona a skill; marketing não. Um acionamento em marketing é falso positivo, não aprovação da qualidade do pacote.
- Mudança quebradora: Tornar cep obrigatório rejeita a entrada antiga sem cep; o relatório classifica a mudança como quebradora para esse consumidor e aponta migração/compatibilidade necessária.
- Bloqueio do recurso ausente: Quando o script está ausente, o resultado é bloqueio de execução com inspeção manual declarada. Não aparece 'script passou'; instruções, recursos e versão permanecem identificados.
Um erro frequente
Skill sempre aprovada é confiável.
Uma skill precisa detectar falhas e recusar tarefas fora do escopo.
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.
- Custom instructions with AGENTS.md
OpenAI • consulta: 2026-10-06
OpenAIAgentesInstruções globais e de projeto, descoberta, AGENTS.override.md e precedência por diretório.
Limites: Precedência documentada para Codex; instruções são orientação, não garantia de cumprimento ou controle de acesso.
- 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.