coursmith-course

Criar e publicar um curso no Coursmith

Você escreve um curso como uma pasta contendo course.json e um diretório assets/, verifica-o com a CLI coursmith e o submete. Um agente de revisão no portal então o aprova, solicita uma revisão ou o rejeita. Seu trabalho termina quando o curso é aprovado, ou quando você explicou o resultado da revisão ao usuário.

Execute a CLI como npx --yes coursmith@latest <comando> --json. O pacote npm público inclui a CLI e esta skill; nenhum acesso ao GitHub ou instalação global é necessário. Se npx estiver ausente, peça ao usuário para instalar o Node.js 20 ou mais recente e siga o guia em /install. Com --json, cada comando imprime um documento JSON; leia-o em vez de adivinhar.

Arquivos de referência nesta pasta de skill (leia-os quando você alcançar a etapa correspondente):

Arquivo	Use para
references/course.schema.json	A estrutura exata de course.json. Chaves desconhecidas são rejeitadas.
references/block-catalog.md	Cada bloco de conteúdo e visual, com exemplos JSON válidos e regras.
references/animation-presets.md	Os 7 presets de animação e quando usar cada um.
references/writing-guide.md	Como escrever etapas, glossários e testes que passem na revisão.
references/content-policy.md	O que não é permitido e como tratar tópicos sensíveis.
examples/sample-course/	Um curso completo que passa na validação. Copie seu formato.

1. Fazer login

1. Execute npx --yes coursmith@latest whoami --json. Se imprimir um username, vá para a etapa 2.
2. Caso contrário, execute npx --yes coursmith@latest login --no-wait --json. Mostre ao usuário o verificationUri e o userCode e peça para ele abrir o link, verificar o código e clicar em Aprovar.
3. Quando o usuário confirmar, execute npx --yes coursmith@latest login --resume --json e verifique se imprime logged_in.

2. Concordar sobre o curso com o usuário

Pergunte, em uma única mensagem, por qualquer coisa que o usuário ainda não forneceu:

• Tópico e, se útil, o ângulo ou público-alvo.
• Idioma do curso (qualquer idioma; você precisará do código BCP-47, como pt, en, pt-BR).
• Dificuldade: beginner, intermediate ou advanced.
• Opcional: duração desejada (padrão cerca de 30 minutos), pré-requisitos, coisas para incluir ou evitar.

Verifique o tópico em relação a references/content-policy.md. Se não for permitido, diga isso e pare. Se for um tópico sensível (saúde, direito, finanças, política, religião…), planeje um tratamento neutro e um aviso de isenção de responsabilidade.

3. Propor um sumário e obter aprovação

Mostre ao usuário:

• título, subtítulo de uma linha, 2–6 objetivos de aprendizado;
• 3–6 seções, cada uma com um resumo de uma linha e 2–5 títulos de etapas;
• para cada etapa, o visual que você planeja (gráfico, diagrama, preset de animação, imagem ou nenhum);
• o número planejado de perguntas do teste (pelo menos 10, cobrindo cada seção).

Revise até o usuário concordar. Não escreva course.json antes disso.

4. Escrever o curso

Crie uma nova pasta com o nome do curso (kebab-case) contendo course.json e assets/. Siga exatamente references/course.schema.json e copie a estrutura de examples/sample-course/course.json.

Regras que o validador impõe (detalhes em references/block-catalog.md):

• schemaVersion é "1.0". Não escreva courseId: a CLI gerencia isso.
• Todos os ids são letras minúsculas, dígitos e travessões, únicos em todo o curso (seções, etapas, assets, perguntas do teste).
• Cada etapa tem um title e pelo menos um bloco; a maioria das etapas também tem um visual.
• Glossário: cada seção tem um glossary que define cada conceito que introduz e cada termo técnico ou de domínio que usa. No texto, marque cada termo como [[termo]], ou [[termo|texto exibido]] quando a redação for diferente (use aliases para plurais e flexões). Um termo marcado deve ser definido na mesma seção ou em uma anterior. As definições são autocontidas e escritas no idioma do curso.
• Visuais: gráficos são especificações Vega-Lite com data.values inline (sem URLs); diagramas são Mermaid sem click ou %%{init}%%; animações usam um dos 7 presets; imagens referem-se a um asset por id.
• Markdown: sem HTML bruto, sem imagens Markdown (use um bloco de imagem), links devem ser https://.
• Teste final: pelo menos 10 perguntas; cada seção é testada por pelo menos uma pergunta (sectionRef); cada pergunta tem uma explanation. Tipos: single, multiple, true_false, ordering (itens de ordenação são listados na ordem correta; o portal os embaralha).
• Perguntas check opcionais no final de uma etapa fornecem feedback rápido aos alunos e não são pontuadas.

Escreva seção por seção e mantenha o idioma, a dificuldade e a terminologia consistentes em todo o curso (veja references/writing-guide.md).

5. Criar os assets

• Uma imagem de capa é obrigatória (meta.coverImage), idealmente 1200×630.
• Se você tiver uma ferramenta de geração de imagens, produza arquivos PNG, JPEG ou WebP. Caso contrário, escreva SVG limpo manualmente: formas simples, uma paleta clara, viewBox definido, sem scripts, sem links externos ou fontes, sem imagens incorporadas.
• Para uma animação highlight-svg, dê aos elementos a serem destacados um atributo id.
• Coloque cada arquivo diretamente em assets/ e declare-o em assets[] com kind (image ou svg), file (assets/<nome>) e um texto alt significativo. Preencha generatedBy para imagens geradas por IA.
• Cada arquivo deve ter menos de 3 MB; o pacote inteiro menos de 25 MB.

6. Validar até estar limpo

Execute npx --yes coursmith@latest validate <pasta> --json. Ele imprime { "ok": ..., "issues": [...] }; cada problema tem severity, code, path (por exemplo sections[1].steps[0].blocks[2]) e message.

Corrija cada error, então execute novamente. Repita até que ok seja true. Corrija avisos também quando forem baratos (por exemplo glossary.unreferenced: marque o termo com [[...]] onde ele é usado).

7. Submeter e acompanhar a revisão

1. Execute npx --yes coursmith@latest submit <pasta> --json. Ele envia o curso e imprime status: "in_review" com um submissionId. A CLI escreve .coursmith.json na pasta; mantenha-o, pois ele vincula submissões posteriores ao mesmo curso.
2. Execute npx --yes coursmith@latest status --dir <pasta> --wait --json (ele espera até 10 minutos; execute novamente se o status ainda for in_review).
3. Aja de acordo com o status:
   • approved: forneça ao usuário o courseUrl. Mencione quaisquer sugestões opcionais em review.issues.
   • needs_revision: para cada problema em review.issues, abra o elemento em path, aplique a suggestion (ou corrija o que message descreve), então valide e submeta novamente. Diga ao usuário o que você alterou. Problemas com severity: "warning" são opcionais.
   • rejected: explique review.summary ao usuário. Não reenvie o mesmo conteúdo.

Se submit relatar review_in_progress, aguarde a revisão atual com status --wait primeiro.

Atualizando um curso publicado

Edite a mesma pasta (mantenha .coursmith.json) e submeta novamente. A nova versão passa por revisão enquanto a atual permanece online; mantenha os ids das etapas estáveis para que os alunos mantenham seu progresso.

Solução de problemas

Saída da CLI	O que fazer
not_logged_in / código de saída 3	Volte para a etapa 1.
client_outdated	Tente novamente com npx --yes coursmith@latest para que o npm busque a CLI mais recente.
validation_failed do submit	Execute validate e corrija os problemas listados.
rate_limited	O usuário atingiu o limite diário de submissão; tente novamente amanhã.
assets.content_type / assets.invalid	O conteúdo do arquivo não corresponde à sua extensão, ou está corrompido. Reexporte-o.
animation.unknown_element	O SVG não possui um elemento com esse id (ids são mantidos, scripts e links externos são removidos).