scaffold-exercises

Visão geral da skill scaffold-exercises

A skill scaffold-exercises ajuda um agente a criar estruturas de pastas de exercícios que seguem uma convenção rígida de conteúdo de treinamento: seções numeradas, exercícios numerados, subpastas de variantes como problem/, solution/ e explainer/, além de arquivos mínimos válidos o bastante para passar em verificações orientadas a lint. Se você está montando material de curso, exercícios de workshop ou um repositório de aprendizagem estruturado, esse é exatamente o problema real que ela resolve.

Para que scaffold-exercises funciona melhor

Use scaffold-exercises quando você já souber o plano de aprendizagem e precisar gerar o esqueleto no filesystem do jeito certo, com rapidez e consistência. Ela é mais indicada para:

• configurar uma nova seção de curso em exercises/
• criar vários stubs de exercícios a partir de um outline curricular
• adicionar variantes problem, solution ou explainer sem ter que adivinhar regras de nomenclatura
• evitar diretórios iniciais quebrados que depois falham no lint do repositório

Quem deve instalar scaffold-exercises

O perfil ideal é alguém trabalhando em um repo que já usa uma estrutura de ensino baseada em exercícios. A scaffold-exercises skill é especialmente útil para maintainers, autores de currículo e editores de repo assistidos por IA que precisam mais de caminhos corretos e arquivos placeholder do que de geração de texto.

O que diferencia scaffold-exercises de um prompt genérico

Um prompt comum pode pedir a uma IA para “criar algumas pastas de exercício”, mas scaffold-exercises adiciona disciplina específica de repositório:

• pastas de seção usam XX-section-name
• pastas de exercício usam XX.YY-exercise-name
• os nomes seguem dash-case
• cada exercício precisa de pelo menos uma pasta de variante
• cada variante precisa de um readme.md não vazio
• arquivos de código como main.ts só são necessários quando realmente existe código

Isso significa menos caminhos malformados, menos placeholders vazios e menos retrabalho depois da geração.

A principal pergunta para decidir a adoção

Instale scaffold-exercises se o seu maior risco for desvio de estrutura, e não falta de originalidade no conteúdo. Essa skill é sobre scaffolding em conformidade com convenções. Ela não é, sozinha, um planejador completo de currículo, redator de aulas nem gerador de código.

Como usar a skill scaffold-exercises

Como a instalação de scaffold-exercises normalmente funciona

O trecho do repositório não publica um instalador próprio dentro de SKILL.md, então o uso depende do runtime de skills que você tiver. Em setups baseados em Skills, é comum que as equipes adicionem o repo de origem e depois invoquem a skill scaffold-exercises pelo nome. Se o seu ambiente suportar, um padrão comum é:

npx skills add mattpocock/skills --skill scaffold-exercises

Se a sua plataforma de agentes carregar skills de outra forma, aponte para o repositório mattpocock/skills e selecione scaffold-exercises.

Leia este arquivo antes de usar scaffold-exercises

Comece por:

• scaffold-exercises/SKILL.md

Essa skill é simples e autocontida. No preview do repositório, não aparecem rules/, resources/ nem scripts auxiliares extras, então a maior parte do comportamento útil está codificada diretamente nesse único arquivo.

Que entrada scaffold-exercises precisa de você

A skill funciona melhor quando você fornece um plano com quatro itens:

1. o número e o título da seção
2. os números e os títulos dos exercícios
3. quais variantes cada exercício deve incluir
4. se você quer apenas stubs ou código inicial real

Sem isso, o agente ainda consegue montar o scaffold, mas vai assumir defaults que talvez você não queira, especialmente na escolha entre explainer/ e problem/.

O prompt mínimo que funciona

Um prompt de scaffold-exercises usage simples, mas funcional, seria assim:

Use scaffold-exercises to create section 03-search-fundamentals under exercises/. Add exercises 03.01-tokenization-basics and 03.02-bm25-ranking. Each should have problem/ and solution/ folders with non-empty readme.md files. Stub only, no code yet.

Isso já basta porque informa numeração, nomes, localização e tipos de variante.

Um prompt melhor para aumentar a qualidade da saída com scaffold-exercises

Um prompt melhor deixa os defaults explícitos:

Use scaffold-exercises for Skill Scaffolding in this repo. Create exercises/03-search-fundamentals/. Add:

• 03.01-tokenization-basics with explainer/
• 03.02-bm25-ranking with problem/ and solution/
• 03.03-query-expansion with problem/

For each variant, create a non-empty readme.md with the final exercise title and a one-sentence description. Do not add main.ts unless the variant includes code. Keep all names dash-case.

Por que isso funciona melhor:

• elimina ambiguidades sobre as variantes de pasta
• evita arquivos de código desnecessários
• preserva as convenções de nomenclatura desde o início
• diz ao agente o que “non-empty” deve significar na prática

Comportamento padrão esperado quando o plano está incompleto

Um dos detalhes mais importantes da skill original: ao gerar stubs, o padrão é usar explainer/, a menos que o plano diga o contrário. Isso é útil para exercícios conceituais, mas pode ser inadequado se o que você precisa mesmo forem workspaces para alunos. Se você quer atividades práticas, especifique problem/ explicitamente.

O que scaffold-exercises vai criar

A skill é orientada a um padrão de diretórios repetível, como:

• exercises/01-section-name/
• exercises/01-section-name/01.01-exercise-name/problem/readme.md
• exercises/01-section-name/01.01-exercise-name/solution/readme.md

Para scaffolds de stub, pastas com apenas readme.md são aceitáveis. Se você adicionar código depois, aí sim main.ts deve existir e conter mais do que um placeholder trivial de uma linha.

Fluxo de trabalho prático para usar scaffold-exercises em um repo real

Um bom fluxo é:

1. Rascunhar o outline do currículo em linguagem natural.
2. Converter isso em nomes numerados de seções e exercícios.
3. Definir as variantes de cada exercício.
4. Pedir ao agente para executar scaffold-exercises.
5. Revisar os nomes dos caminhos antes de adicionar conteúdo.
6. Rodar o lint ou a etapa de validação do repo.
7. Só então preencher código e documentação mais completa.

Essa ordem importa porque a skill funciona melhor quando a estrutura vem primeiro.

Erros de nomenclatura que mais geram retrabalho

As entradas ruins mais comuns são:

• ausência de prefixos numéricos
• uso de espaços em vez de dash-case
• confusão entre numeração de seção e numeração de exercício
• omissão de quais pastas devem ser problem, solution ou explainer

Se o seu plano diz “Crie um exercício sobre BM25”, o agente ainda precisa inventar coisa demais. Se ele diz “Crie 01.03-retrieval-with-bm25 dentro de 01-retrieval-skill-building com problem/ e solution/”, o resultado costuma ser confiável.

Orientação de fit para scaffold-exercises em Skill Scaffolding

scaffold-exercises for Skill Scaffolding é uma boa escolha quando o seu gargalo está no formato do repo e na consistência. É uma escolha fraca quando você precisa que pedagogia, avaliações ou explicações refinadas sejam geradas automaticamente. Trate a skill como um mecanismo de imposição de estrutura, não como substituto de design instrucional.

FAQ da skill scaffold-exercises

scaffold-exercises é amigável para iniciantes?

Sim, desde que você já entenda qual estrutura de exercícios quer criar. A skill em si é simples: ela basicamente impõe nomenclatura, organização de pastas e os arquivos mínimos exigidos. A parte mais difícil é decidir antes o currículo e as variantes.

Quando eu não devo usar scaffold-exercises?

Evite scaffold-exercises se:

• seu repo não usa pastas numeradas de seção e exercício
• você precisa apenas de uma lição em markdown, não de uma árvore de exercícios
• você quer que a IA invente a arquitetura do curso do zero
• seu projeto usa um contrato de arquivos diferente de readme.md com main.ts opcional

Em que scaffold-exercises difere de criar pastas manualmente

Fazer o scaffold manualmente funciona bem para um único exercício. O valor de scaffold-exercises usage aparece quando você cria muitos exercícios e precisa de consistência. Ela reduz a chance de nomes inválidos, readmes vazios e convenções mistas de pastas que quebram verificações posteriores.

scaffold-exercises gera o conteúdo completo do exercício?

Não. O valor central dela é o scaffolding. Ela pode criar readmes mínimos e a estrutura placeholder, mas você não deve tratá-la como um sistema completo de autoria de aulas.

Eu preciso de problem, solution e explainer toda vez?

Não. As regras originais exigem apenas pelo menos um deles. Para stubs, explainer/ é o padrão quando nada mais é especificado. Escolha as variantes com base no objetivo do exercício, não por hábito.

scaffold-exercises está presa a um único layout de repo?

Ela é opinativa. A skill assume uma hierarquia exercises/ e convenções específicas de numeração. Se o seu repo segue esse padrão, ela é útil. Caso contrário, você vai gastar tempo brigando com as premissas dela.

Como melhorar o uso da skill scaffold-exercises

Dê ao scaffold-exercises um plano numerado, não uma lista de tópicos

A forma mais rápida de obter resultados melhores com scaffold-exercises é parar de usar temas como prompt e começar a informar caminhos-alvo exatos. Compare:

Fraco:

• “Add some exercises about retrieval.”

Forte:

• “Create exercises/01-retrieval-skill-building/01.01-keyword-search, 01.02-bm25, and 01.03-hybrid-search.”

O segundo prompt quase não deixa margem para o agente nomear pastas de forma errada.

Especifique a intenção das variantes em vez de deixar os defaults decidirem

Se você omitir os tipos de variante, a skill pode escolher explainer/ para os stubs. Isso é eficiente, mas pode não bater com o desenho didático que você quer. Diga:

• use problem/ para tarefas dos alunos
• use solution/ para referências
• use explainer/ para material apenas conceitual

Essa única clarificação melhora materialmente a qualidade do scaffold.

Peça readmes mínimos, mas válidos

Um modo comum de falha é gerar placeholders que tecnicamente existem, mas não ajudam em nada. Diga ao agente para colocar um título e uma descrição de uma frase em cada readme.md. Isso mantém os arquivos não vazios e facilita a autoria posterior.

Evite arquivos de código desnecessários

Outro erro comum é gerar main.ts em todo lugar. A skill original não exige isso para stubs só com readme. Se você quer um scaffold leve, diga “readme-only unless code is explicitly needed”. Isso deixa a primeira passada mais limpa.

Valide os nomes antes de gerar muitos exercícios

Para lotes grandes, peça ao agente primeiro uma lista dos caminhos propostos e só depois a criação, após aprovação. Isso captura colisões de numeração e slugs estranhos antes de você ter que renomear dezenas de pastas.

Itere depois da primeira passada com scaffold-exercises

Depois da primeira execução, melhore o resultado revisando:

• continuidade da numeração
• completude das variantes
• utilidade dos readmes
• se cada exercício realmente pertence à seção escolhida

Depois peça ao agente uma segunda passada focada apenas em correções. A qualidade do scaffold-exercises guide melhora de forma perceptível quando geração e revisão são separadas.

Onde scaffold-exercises ainda exige julgamento humano

A scaffold-exercises skill não consegue decidir por você a sequência didática ideal, a dificuldade dos exercícios nem a cobertura pedagógica adequada. Os melhores resultados vêm de usar a skill para automatizar a estrutura e manter a revisão humana para a lógica curricular.