Coursmithコースの作成と公開

コースは、course.jsonとassets/ディレクトリを含むフォルダとして作成し、coursmith CLIでチェックして提出します。ポータル上のレビューエージェントが承認、修正要求、または却下を行います。コースが承認されるか、レビュー結果をユーザーに説明するまでが作業の終了です。

CLIはnpx --yes coursmith@latest <command> --jsonで実行します。公開npmパッケージにはCLIとこのスキルが含まれています。GitHubへのアクセスやグローバルインストールは不要です。npxがない場合は、ユーザーにNode.js 20以降をインストールし、/installのガイドに従うよう依頼してください。--jsonを指定すると、すべてのコマンドが1つのJSONドキュメントを出力します。推測せずに読み取ってください。

このスキルフォルダ内の参照ファイル（該当するステップに到達したら読んでください）：

ファイル	用途
`references/course.schema.json`	`course.json`の正確な構造。未知のキーは拒否されます。
`references/block-catalog.md`	すべてのコンテンツブロックとビジュアル、有効なJSONの例とルール。
`references/animation-presets.md`	7つのアニメーションプリセットとその使用タイミング。
`references/writing-guide.md`	レビューに合格するステップ、用語集、クイズの書き方。
`references/content-policy.md`	許可されていないものと、センシティブなトピックの扱い方。
`examples/sample-course/`	バリデーションに合格する完全なコース。その構造をコピーしてください。

1. ログイン

npx --yes coursmith@latest whoami --jsonを実行します。usernameが出力されたら、ステップ2に進みます。
そうでない場合は、npx --yes coursmith@latest login --no-wait --jsonを実行します。ユーザーにverificationUriとuserCodeを表示し、リンクを開いてコードを確認し、承認をクリックするよう依頼します。
ユーザーが確認したら、npx --yes coursmith@latest login --resume --jsonを実行し、logged_inが出力されることを確認します。

2. ユーザーとコース内容を合意する

ユーザーがまだ提供していない情報を、1つのメッセージで尋ねてください：

トピックと、必要に応じてアングルや対象者。
コースの言語（任意の言語。BCP-47コード（例：it、en、pt-BR）が必要です）。
難易度：beginner、intermediate、advancedのいずれか。
オプション：希望する長さ（デフォルト約30分）、前提条件、含めるものや避けるもの。

references/content-policy.mdに対してトピックを確認します。許可されていない場合は、その旨を伝えて停止します。センシティブなトピック（健康、法律、金融、政治、宗教など）の場合は、中立的な扱いと免責事項を計画してください。

3. アウトラインを提案し、承認を得る

ユーザーに以下を提示します：

タイトル、1行のサブタイトル、2～6の学習目標；
3～6のセクション。各セクションに1行の要約と2～5のステップタイトル；
各ステップに計画するビジュアル（チャート、図、アニメーションプリセット、画像、なし）；
計画されたクイズ問題の数（最低10問、すべてのセクションをカバー）。

ユーザーが同意するまで修正します。それ以前にcourse.jsonを書かないでください。

4. コースを書く

コース名（ケバブケース）の新しいフォルダを作成し、course.jsonとassets/を配置します。references/course.schema.jsonに正確に従い、examples/sample-course/course.jsonの構造をコピーしてください。

バリデーターが強制するルール（詳細はreferences/block-catalog.md）：

schemaVersionは"1.0"です。courseIdは書かないでください：CLIが管理します。
すべてのIDは小文字、数字、ダッシュで構成され、コース全体（セクション、ステップ、アセット、クイズ問題）で一意です。
すべてのステップにはtitleと少なくとも1つのブロックがあり、ほとんどのステップにはvisualもあります。
用語集：すべてのセクションには、そのセクションで導入する概念と、使用するすべての技術用語またはドメイン用語を定義するglossaryが必要です。テキスト内では、各用語を[[term]]または、表現が異なる場合は[[term|表示テキスト]]としてマークします（複数形や語形変化にはaliasesを使用します）。マークされた用語は、同じセクションまたはそれ以前のセクションで定義されている必要があります。定義は自己完結的で、コース言語で記述します。
ビジュアル：チャートはインラインのdata.valuesを持つVega-Lite仕様（URLは不可）。図はclickや%%{init}%%なしのMermaid。アニメーションは7つのプリセットのいずれかを使用。画像はIDでアセットを参照します。
Markdown：生のHTMLは不可、Markdown画像は不可（画像ブロックを使用）、リンクはhttps://である必要があります。
最終クイズ：最低10問。すべてのセクションが少なくとも1つの問題（sectionRef）でテストされます。すべての問題にexplanationが必要です。タイプ：single、multiple、true_false、ordering（順序付け項目は正しい順序でリストされ、ポータルがシャッフルします）。
オプションのcheck問題は、ステップの最後に学習者にクイックフィードバックを提供し、採点されません。

セクションごとに書き、言語、難易度、用語を一貫させてください（references/writing-guide.md参照）。

5. アセットを作成する

カバー画像が必要です（meta.coverImage）。理想的には1200×630です。
画像生成ツールがある場合は、PNG、JPEG、またはWebPファイルを作成します。そうでない場合は、手書きでクリーンなSVGを作成します：シンプルな形状、クリアなパレット、viewBox設定、スクリプトなし、外部リンクやフォントなし、埋め込み画像なし。
highlight-svgアニメーションの場合は、ハイライトする要素にid属性を付与します。
すべてのファイルをassets/に直接配置し、kind（imageまたはsvg）、file（assets/<name>）、意味のあるaltテキストをassets[]で宣言します。AI生成画像の場合はgeneratedByを入力します。
各ファイルは3MB未満、全体のバンドルは25MB未満である必要があります。

6. バリデーションが通るまで繰り返す

npx --yes coursmith@latest validate <folder> --jsonを実行します。{ "ok": ..., "issues": [...] }が出力され、各問題にはseverity、code、path（例：sections[1].steps[0].blocks[2]）、messageが含まれます。

すべてのerrorを修正し、再度実行します。okがtrueになるまで繰り返します。コストが低い場合（例：glossary.unreferenced：使用箇所で[[...]]で用語をマーク）は、警告も修正します。

7. 提出し、レビューに従う

npx --yes coursmith@latest submit <folder> --jsonを実行します。コースをアップロードし、status: "in_review"とsubmissionIdを出力します。CLIはフォルダ内に.coursmith.jsonを書き込みます。これは後の提出を同じコースにリンクするために保持してください。
npx --yes coursmith@latest status --dir <folder> --wait --jsonを実行します（最大10分待機します。ステータスがまだin_reviewの場合は再度実行します）。
statusに応じて行動します：
- approved：ユーザーにcourseUrlを提供します。review.issuesのオプションの提案があれば言及します。
- needs_revision：review.issuesの各問題について、pathにある要素を開き、suggestionを適用するか（またはmessageが説明する内容を修正し）、バリデーションしてから再提出します。変更した内容をユーザーに伝えます。severity: "warning"の問題はオプションです。
- rejected：review.summaryをユーザーに説明します。同じ内容を再提出しないでください。

submitがreview_in_progressを報告した場合は、最初にstatus --waitで現在のレビューを待ちます。

公開済みコースの更新

同じフォルダを編集し（.coursmith.jsonを保持）、再度提出します。新しいバージョンはレビューを受けますが、現在のバージョンはそのままオンラインで維持されます。学習者の進捗が維持されるよう、ステップIDは安定させてください。

トラブルシューティング

CLI出力	対処法
`not_logged_in` / 終了コード3	ステップ1に戻ります。
`client_outdated`	`npx --yes coursmith@latest`で再試行し、npmが最新のCLIを取得するようにします。
`submit`から`validation_failed`	`validate`を実行し、リストされた問題を修正します。
`rate_limited`	ユーザーが1日の提出制限に達しました。明日再試行してください。
`assets.content_type` / `assets.invalid`	ファイルの内容が拡張子と一致しないか、破損しています。再エクスポートしてください。
`animation.unknown_element`	SVGにその`id`を持つ要素がありません（IDは保持され、スクリプトと外部リンクは削除されます）。

coursmith-course