seaslides-typst-slides-skill

SeaSlides Typst スライドスキル

ユーザーの意図に合わせたレビューの深さで、ソース資料をコンパイル済みの Touying/Typst プレゼンテーションに変換します。

フルパイプライン：Source -> Project -> Theme -> Strategist -> [Images] -> Executor -> Compile -> Review -> Export

クイックパイプライン：Source -> Project -> Existing Theme -> Author -> Compile -> [Review] -> Export

目次

• 必須要件
• モードの振り分け
• シナリオの振り分け
• リソース一覧
• フルモードのワークフロー
• 既存デッキの編集
• 依存関係

必須要件

1. 選択したモードの各フェーズを順番に実行します。次のフェーズに進む前に、各ゲートを完了してください。
2. 処理を妨げるゲートでは、必要な判断をユーザーに求めます。無人モードでは判断を行い、そのまま続行してください。
3. スライドの計画を立てる前に、PDF、DOCX、PPTX、スプレッドシート、ウェブ上の資料を Markdown に変換します。
4. コンテンツとテーマに関する作業は分けてください。Plain/Rich モードでは、main.typ に場当たり的な視覚スタイルを追加しないでください。
5. プロジェクト所有およびカスタムのテーマでは、Touying を正確に #import "@preview/touying:0.7.4": * としてインポートします。サードパーティ製の Universe テーマが古い Touying の推移的バージョンを使用している場合は、そのパッケージで文書化されている API を使用し、競合する直接インポートの追加やパッケージキャッシュの編集は行わないでください。
6. コンパイル、機械的な品質チェック、検証を行ってから納品します。視覚レビューの深さはユーザーの依頼に合わせてください。ユーザーが明示的にレビューを行わないよう求めた場合は、視覚検査を省略し、出力を視覚レビューしていないことを明記します。
7. output/slides.pdf と output/overview.png がないプロジェクトは未完成として扱います。
8. すべてのスライドに #speaker-note[...] を追加します。
9. クイックモードでは、${SKILL_DIR}/workflows/quick-mode.md の定義に従って、個別のデザイン仕様書と役割の参照のみを省略します。ルール 3〜8 は引き続き適用されます。
10. 起動時と各フェーズの切り替え時に、モード、現在のフェーズ、実行する作業をユーザーの言語で簡潔に伝えます。作業を妨げる問題が発生した場合や、約 1 分間進捗がない場合にも状況を更新してください。個々のコマンドについて逐一説明する必要はありません。
11. 既存のエディターまたはユーザーのワークスペースは、その場で再利用します。その中でプロジェクトの初期化を実行してはいけません。また、アクティブなワークスペース相対パスの Typst エントリを、すべてのコンパイル、監査、検証の手順に渡してください。

Typst/Touying の要件およびアンチパターンの基準として、${SKILL_DIR}/references/shared-standards.md を使用してください。

モードの振り分け

ユーザーが明示的に速度を優先する場合、最初に使えるドラフトを求める場合、または妥当なデフォルトを受け入れる場合は、クイックモードを使用します。${SKILL_DIR}/workflows/quick-mode.md に従ってください。

標準のパイプラインにはフルモードを使用します。また、新しいテーマや大幅に拡張したテーマ、新しい画像の取得、大規模な調査や情報源の収集、正式なデザイン仕様書、複雑なグラフの調整、長いデッキのフェーズ再開が必要な場合も、フルモードを使用します。

クイックモードはワークフローの選択肢であり、Plain、Rich、Canvas はテーマの複雑さの段階です。同等に適合するなら、作成がより速い Rich または Plain を優先してください。選択した既存テーマの theme.md と demo.typ に、明確でコンパイル可能な方法がすでに示されている場合は、Canvas も選択できます。名前が指定されたテーマ、ひな形として用意されたテーマ、既存テーマは、どちらのモードでも優先してください。

クイックモードでは、追加の判断ゲートを設けずに、視覚レビューの深さを判断します。明示的なレビュー不要の指定があれば従い、通常の迅速なドラフトでは対象を絞ったレビューを行い、ユーザーが視覚面の保証や納品品質のレビューを求める場合は、すべてのページを確認してください。

シナリオの振り分け

標準的なスライド作成パイプラインに進む前に、特殊な出力を振り分けます。

意図	読んで従うファイル
学術ポスターまたは学会ポスター	${SKILL_DIR}/references/scenarios/poster.md
CV または履歴書	${SKILL_DIR}/references/scenarios/cv.md
ソーシャルメディアのカバー画像、記事ヘッダー、またはサムネイル	${SKILL_DIR}/references/scenarios/social-cover.md
標準的なプレゼンテーションまたはスライドデッキ	以下に進む

ユーザーの言語に合わせます。content_design_spec.md のセクション見出しは英語にし、適切な場合はフィールド値をユーザーの言語で記述します。

25 枚以上のスライドで構成される Rich/Canvas デッキでは、${SKILL_DIR}/workflows/resume-execute.md を使って、計画と実行を複数のセッションに分けます。

リソースマップ

該当するフェーズに入るときにのみ、参照ファイルを読み込みます。

ワークフローの振り分け

タスク	リソース
全体の作成ワークフロー	${SKILL_DIR}/workflows/create-presentation.md
クイック作成ワークフロー	${SKILL_DIR}/workflows/quick-mode.md
テーマの選択	${SKILL_DIR}/workflows/select-theme.md
新しいテーマの作成	${SKILL_DIR}/workflows/create-template.md
トピックのみの調査	${SKILL_DIR}/workflows/topic-research.md
長いデッキの再開	${SKILL_DIR}/workflows/resume-execute.md
グラフの調整	${SKILL_DIR}/workflows/verify-charts.md
ビジュアルレビュー	${SKILL_DIR}/workflows/visual-review.md
音声ナレーション	${SKILL_DIR}/workflows/generate-audio.md

参照情報の優先順位

各行のリソースを、その項目に関する唯一の基準として扱います。現在のフェーズで必要な場合にのみ、詳細ファイルを読み込みます。

項目	基準となるリソース	読み込むタイミング
Typst/Touying の構文、TCS、レイアウトの安全性、厳守事項	${SKILL_DIR}/references/shared-standards.md	Typst 出力の計画または作成時
高度な表、数式、アイコン、SVG、シャドウ、画像ソースのレシピ	${SKILL_DIR}/references/shared-standards-extended.md	基本基準からリンクされている場合、または高度な機能が必要な場合
ビジュアルの方向性、構成、リズム、美的なアンチパターン	${SKILL_DIR}/references/design-guide.md	ビジュアルの方向性を定めるとき、またはテーマ／Canvas を高品質に作り込むとき
コンテンツ戦略と content_design_spec.md	${SKILL_DIR}/references/strategist.md	ストラテジストのフェーズ
すべてのプレゼンテーションスタイルに共通する Full Mode の実行ワークフロー	${SKILL_DIR}/references/executors/base.md	スタイル別エグゼキューターを 1 つだけ読み込む前
テーマファイル、公開コンポーネント API、デモ、テーマの品質基準	${SKILL_DIR}/references/template-designer.md	テーマを作成するとき、または大幅に拡張するとき
画像の取得方法の振り分け	${SKILL_DIR}/references/image-base.md	デザイン仕様で新しい画像が求められている場合
AI 画像の生成とレンダリングスタイル	${SKILL_DIR}/references/image-generator.md および ${SKILL_DIR}/references/image-renderings/_index.md	image-base.md で AI の経路が選択された場合
ライセンス付きウェブ画像の検索と帰属表示	${SKILL_DIR}/references/image-searcher.md	image-base.md でウェブ検索の経路が選択された場合
画像配置の用語	${SKILL_DIR}/references/image-layout-patterns.md	画像の多いページを計画または実装するとき
レンダリング後のビジュアルレビュー	${SKILL_DIR}/references/visual-review.md	選択したレビュー方針でレンダリング結果の確認が求められる場合
ビジュアル上の問題の担当範囲と修正先の振り分け	${SKILL_DIR}/references/artifact-ownership.md	不具合が確認された場合

レンダリングスタイルの詳細は ${SKILL_DIR}/references/image-renderings/<anchor>.md にあります。ファイルを読み込む前に、レンダリングインデックスからアンカーを 1 つ選択してください。任意の制御比較ギャラリーは ${SKILL_DIR}/references/ai-image-comparison/README.md に記載されており、${SKILL_DIR}/references/ai-image-comparison/_index.md からも参照できます。

エグゼキューターのスタイル振り分け

この振り分けは Full Mode でのみ適用します。エグゼキューターのベースと、一致するスタイルファイルをちょうど1つ読み込みます。 複雑さの段階とエグゼキューターのスタイルは別々に判断します。Canvas では Canvas エグゼキューターを使用し、 Canvas 以外のスタイルファイルは読み込みません。Quick Mode ではエグゼキューターの参照資料を読み込みません。

プレゼンテーションの目的	スタイルリソース
製品、研修、提案、マーケティング、または汎用のスライド資料	${SKILL_DIR}/references/executors/general.md
ビジネスレビュー、業績レポート、またはデータ中心のコンサルティング資料	${SKILL_DIR}/references/executors/consultant.md
取締役会、投資、またはMBBスタイルの経営層向け提言	${SKILL_DIR}/references/executors/consultant-top.md
カンファレンストーク、論文発表、セミナー、または研究発表	${SKILL_DIR}/references/executors/academic.md
エディトリアル、スイス、フェスティバル、またはページ単位で個別に構成する資料	${SKILL_DIR}/references/executors/canvas.md

学術ポスターはシナリオ別ワークフローに従うため、学術スライドのエグゼキューターは使用しません。

リソースハブとカタログ

必要なもの	人が読めるハブ	機械可読または直接利用するリソース
スクリプトの検索と運用ドキュメント	${SKILL_DIR}/scripts/README.md	${SKILL_DIR}/scripts/docs/
テンプレートリソースの検索	${SKILL_DIR}/templates/README.md	以下のカテゴリ別インデックス
テーマの選択	${SKILL_DIR}/templates/themes/README.md	${SKILL_DIR}/templates/themes/<tier>/index.json
Typst パッケージ	${SKILL_DIR}/templates/packages/README.md	${SKILL_DIR}/templates/packages/index.json
グラフと図	${SKILL_DIR}/templates/charts/README.md	${SKILL_DIR}/templates/charts/index.json
アイコンと記号	${SKILL_DIR}/templates/icons/README.md	${SKILL_DIR}/templates/icons/index.json
コンテンツ計画スキーマ	—	${SKILL_DIR}/templates/content_design_spec_reference.md
テーマデザインスキーマ	—	${SKILL_DIR}/templates/theme_design_spec_reference.md
テーマ API 概要スキーマ	—	${SKILL_DIR}/templates/theme_reference.md

このファイルで個々のテーマ、グラフ、パッケージ、アイコンを列挙しないでください。同梱リソースが進化しても SKILL が安定して保たれるよう、各カタログを使用してください。

Full Mode ワークフロー

Full Mode では、以下の手順に従います。Quick Mode では独立したワークフローに従い、Quick Mode 独自のレビュー方針を適用しながら、以下のコンパイル、品質、検証、エクスポートのコマンドを再利用します。

Step 1: ソースを処理する

ゲート：ソース資料またはトピックが用意されていること。

トピックのみが提供された場合は、${SKILL_DIR}/workflows/topic-research.md に従うか、続行する前にソースブリーフを作成してください。

入力	コマンド
PDF	python3 ${SKILL_DIR}/scripts/source_to_md/pdf_to_md.py <file> --images filtered
DOCX / EPUB / HTML / LaTeX / RST	python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>
PPTX / PPSX	python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <file>
Excel	python3 ${SKILL_DIR}/scripts/source_to_md/excel_to_md.py <file>
ウェブページ	python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <url>
Markdown / テキスト	直接読み込む

変換ツールが利用できる場合は、未読の生ドキュメントだけをもとに作業を進めないでください。

Step 2: ワークスペースを解決する

ゲート：読み取り可能なソースコンテンツが存在すること。

ユーザーまたはホストエディターからすでにワークスペースが提供されている場合は、その場でアタッチします。

python3 ${SKILL_DIR}/scripts/project_manager.py workspace <workspace_path> \
  --entry <workspace-relative-entry.typ> --prepare

これにより、不足している assets/、output/、sources/ の補助ディレクトリのみが作成されます。子プロジェクト、README、置き換え用のエントリーは作成されません。返されたエントリーパスを保持し、以下の --entry に渡してください。Tylina などのホストが信頼できるツールを通じてワークスペースとメインファイルの状態を提供する場合は、ファイル名を推測せず、その状態を使用してください。

ワークスペースが存在しない場合に限り、新しいスタンドアロンプロジェクトを初期化します。

python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name>
python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --copy

再現可能なベンチマークなど、日付を含まない決定的なディレクトリ名が必要な場合に限り、--exact-name を使用します。通常のプロジェクトでは、日付のサフィックスを維持します。

ソースファイルの移動をユーザーが明示的に要求した場合に限り、--move を使用します。抽出したソース画像を <project_path>/assets/ にコピーし、変換済みの Markdown をインポートしてください。

Step 3: テーマを選択または作成する

ゲート：プロジェクトディレクトリが存在すること。

${SKILL_DIR}/workflows/select-theme.md に従ってください。

1. ユーザーがテーマを指定している場合は、そのテーマを直接使用します。
2. それ以外の場合は、テーマのディスパッチと関連カタログを確認し、テーマのメタデータをコンテンツ、対象読者、提供方法に合わせます。
3. 控えめでミニマルな出力をユーザーが求めている場合は Plain を使用します。標準の既定値としては Rich を使用します。
4. 独自の構成が内容に大きく役立ち、実行環境が Typst のコンテンツモードとコードモード、テーマ API、コンパイル確認を正しく扱える場合に限り、Canvas を使用します。不確かな場合は Rich に切り替えます。
5. ライブラリが内容に合わず、実装とビジュアルレビューに十分な時間がある場合に限り、新しいテーマを作成します。

選択後：

python3 ${SKILL_DIR}/scripts/project_manager.py copy-theme <project_path> <name>

コピーした theme.md と demo.typ を読みます。Canvas を使用する場合は、template.typ も読みます。ドキュメントに記載された API と構造パターンを使用し、内容に役立たない装飾の細部を機械的に模倣しないでください。

Step 4: コンテンツ設計仕様を作成する

ゲート：テーマが選択され、内容を把握していること。

次を読みます。

${SKILL_DIR}/references/strategist.md
${SKILL_DIR}/references/shared-standards.md

無人モードが有効な場合を除き、9つの決定事項をひとまとめに提示し、回答を待ちます。

1. ページ形式
2. ページ数の範囲
3. 対象読者
4. スタイルの目標
5. 複雑さのレベル
6. 配色
7. タイポグラフィ計画
8. 画像の方針
9. サードパーティーパッケージ

${SKILL_DIR}/templates/packages/index.json からパッケージを選択します。よく使われる選択肢には、LaTeX 数式用の mitex、標準的なチャート用の lilaq、レイヤー構造の Grammar-of-Graphics プロット用の gribouille、任意のコードスタイル設定用の codly、疑似コード用の lovelace、チェックリスト用の cheq、Mermaid 図用の merman があります。

ユーザーの画像がある場合は、次を実行します。

python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/assets

提供されたテンプレートを基に <project_path>/content_design_spec.md を作成します。プロジェクト設定、具体的なテーマ、パッケージ、ストーリー展開、スライドごとの概要、画像の選定、色、タイポグラフィを記載してください。使用しないアセットを意図的に除外した理由も記録します。

Step 5: 必要に応じて画像を取得する

ゲート：設計仕様で、AI 生成画像または検索画像が指定されていること。

${SKILL_DIR}/references/image-base.md を読み、続いて選択した画像ワークフローを読みます。

python3 ${SKILL_DIR}/scripts/image_gen.py --check-available

アセットマニフェストまたはプロンプトファイルを生成し、画像を作成または検索して、必要なファイルが assets/ に存在することを確認します。設計仕様で新しい画像が不要な場合は、このフェーズを省略します。

ステップ 6：プレゼンテーションを作成する

ゲート：デザイン仕様と必要なアセットが揃っています。

executor のベース、スタイル executor をちょうど 1 つ、共有標準を読みます。Canvas が選択されている場合に限り、Canvas のガイダンスも読みます。

main.typ を作成する前に、コピーした theme.md、demo.typ、content_design_spec.md を読み直します。

次の制約に従って作成します。

• 内容を明確に表現できる場合は、テーマのコンポーネントとレイアウトを使用します。比較ページを繰り返す場合は、意図的に同じレイアウトを使用してかまいません。
• レンダリングされるコンポーネントの引数には、Typst のコンテンツブロックを優先します。ユーザー向けの文言を "Title" のように渡すのではなく、#card[Title][Body]（または #card(accent: palette.accent)[Title][Body]）と記述します。パス、URL、列挙型や設定キー、フォント名、文字列操作が必要な値など、本当に文字列値のデータには文字列を使用します。
• 通常の複数列構成には #cols[...] [...] を使用します。テーマ固有の別のコンポーザーは、その theme.md で明示的に必要とされている場合にのみ使用します。
• 呼び出し元のレベルでは、完全なコンポーネントを自然な流れの中で直接構成します。通常の間隔調整だけを目的に固定の v() を追加したり、隣接するコンポーネントを stack() で囲んだりしないでください。stack(spacing:) は、意図的にひとまとまりの視覚的グループを形成する要素に限って使用します。
• Plain/Rich の main.typ では、その場限りの rgb() や block(fill:) によるスタイル設定を避けます。再利用可能な視覚パターンがない場合は、template.typ を拡張します。
• 関連するアセットやユーザーが必要としたアセットはすべて使用します。存在するという理由だけで無関係な画像を挿入しないでください。除外したアセットはデザイン仕様に記録します。
• タイトル、区切り、ヒーロー、フォーカス、付録のページを、指定されたページ数の範囲に含めます。
• ソースやデバッグ用のテキスト、TODO、未解決のコンポーネント呼び出し、診断情報をレンダリング後のスライドに含めないでください。
• すべてのスライドに、内容のあるスピーカーノートを追加します。

レイアウト、コンポーネント、リズムの多様性は、数値目標ではなく、内容に応じて判断するデザイン上の指針として扱います。比較や順序立てた説明に適している場合は、恣意的に変化をつけるよりも、一貫性のある反復構成を優先します。

ステップ 7：コンパイル、レビュー、検証、エクスポート

ゲート：template.typ と main.typ が存在します。

各サブステップを順番に実行し、ソースを変更した場合はコンパイルを再実行します。

7.1 コンパイル

python3 ${SKILL_DIR}/scripts/typst_compiler.py <project_path> --all --entry <entry.typ>

output/slides.pdf、スライドごとの PNG、output/overview.png、および --all の全シーケンスが成功した後にのみ書き込まれる、一貫性のある output/compile-manifest.json の記録を必須とします。失敗した場合は原因を特定し、最大 5 回まで再試行します。

7.2 機械的な品質チェックを実行する

python3 ${SKILL_DIR}/scripts/typst_quality_checker.py <project_path> --entry <entry.typ>

デフォルトのゲートでは、blocker の診断があると失敗します。コンパイルエラー、出力やリソースの欠落、コンテンツのはみ出し、レイアウトの収束失敗、明示的に指定された想定ページ数との不一致は、ブロッキングとして扱います。フォントのフォールバックや分類されていないコンパイラー警告などの review 診断には、ソースとレンダリング結果の確認が必要です。これらは自動的に視覚上の不具合と判定されるものではありません。Touying のフロー専用 EMPTY_SLIDE シグナルは、配置ベースのページでは目に見える内容があっても発生するため、参考情報として扱います。視覚レビューが有効な場合は、該当する PNG を確認します。ユーザーが視覚レビューをオプトアウトしている場合は、未解決の参考情報として開示し、視覚レビューに合格したとは主張しないでください。ページ数の意図が分かっている場合は --expected-pages N を使用します。機械可読な監査記録が必要な場合は --json <receipt.json> を使用します。

7.3 選択されている場合は視覚レビューを実施する

${SKILL_DIR}/workflows/visual-review.md で選択した範囲を適用します。full の場合は概要画像とすべてのスライドを確認し、targeted の場合は概要画像とチェッカーが問題を指摘したページのみを確認し、none の場合はレンダリング結果の確認を省略します。確認を行う場合は ${SKILL_DIR}/references/visual-review.md を使用し、確認できた不具合を修正して、ソースを変更した後は最大 3 回まで再コンパイルします。

テーマへの忠実度と視覚的な多様性は、文脈に応じて評価します。明確な反復シーケンスを、固定のレイアウト数を満たすためだけに再設計しないでください。

none の場合は、納品時に、デッキはコンパイルされ機械的なチェックを受けたものの、視覚レビューは行われていないと明記します。レビューの範囲と結果は、必ず分けて報告します。

7.4 検証する

python3 ${SKILL_DIR}/scripts/validate_project.py <project_path> --entry <entry.typ>
# Quick Mode only:
python3 ${SKILL_DIR}/scripts/validate_project.py <project_path> --mode quick --entry <entry.typ>

完了前に、報告されたエラーを修正します。

7.5 エクスポート

PDF はすでに output/slides.pdf にあります。選択したレビュー方針が完了するか、明示的にスキップされた後、要求があれば PPTX をエクスポートします。

python3 ${SKILL_DIR}/scripts/typst_compiler.py <project_path> --format pptx

ステップ 8：要求があれば音声を生成する

スライドの出力が安定してから、${SKILL_DIR}/workflows/generate-audio.md に従ってください。

既存のデッキを編集する

1. main.typ、template.typ、テーマのドキュメント、現在のレンダリング出力を探して読みます。
2. コンテンツを変更する場合は main.typ を、再利用可能なスタイルを変更する場合は template.typ を編集します。
3. 再コンパイルし、選択したビジュアルレビュー方針を適用して、検証後に再エクスポートします。
4. 要求された変更によって、ストーリー展開、テーマ、またはデッキの構成が変わる場合に限り、計画を再実行します。

依存関係

pip install -r ${SKILL_DIR}/requirements.txt

uv が利用可能な場合は、呼び出し元のアプリケーションまたはユーザーが管理する分離環境を優先してください。 システム Python にはインストールせず、シェルの起動ファイルも変更しないでください。ホストが管理するランタイムでは、Agent に uv の場所を探させたりインストールさせたりするのではなく、安定したツールインターフェースを通じてこれらのスクリプトを実行してください。

ローカルプレビューには typst watch <project_path>/main.typ を使用します。ただし、納品前にプロジェクトのコンパイラと検証パイプラインを実行してください。