customer-card-render

カスタマーカードレンダリングスキル

標準の Design Thinking Markdown 成果物を PowerPoint スキルの content.yaml スライド定義に変換し、共有 PowerPoint ビルドパイプラインを通じて最終デッキを生成します。

概要

このスキルは、実験的な PowerPoint スキルと連携するスキルです。Design Thinking に特化したマッピングレイヤーを担当し、標準 Markdown 成果物からセクションを抽出して、テンプレート駆動の content.yaml ファイルに入力します。レイアウトのレンダリング、テーマ設定、エクスポート、検証は PowerPoint スキルが担当します。

これらの関心事を分離することで、次の利点が得られます。

• カスタマーカードのマッピングロジックが、一般的な PowerPoint 機能から独立します。
• このスキルをパッケージに個別に含められます。
• レイアウトプリミティブ、Invoke-PptxPipeline.ps1、テーマ設定、検証の動作をここで再実装する必要がありません。

PowerPoint パイプラインの全ドキュメントを確認するには、powerpoint スキルを名前で有効化してください。解決できない場合は、パイプラインのドキュメントとビルド動作を利用できないことをユーザーに警告し、ここで再実装せずに停止してください。

前提条件

• Python 3.11+

• 公開済みのハッシュと照合してダウンロードを検証するパッケージマネージャーでインストールした uv パッケージマネージャー：

  # Windows
  winget install --id astral-sh.uv -e
  
  # macOS / Linux (Homebrew)
  brew install uv
  

  代わりにリリースアーカイブからインストールする場合は、uv のリリースページからダウンロードし、展開する前に .sha256 ファイルと照合してください。

• Invoke-PptxPipeline.ps1 のビルド手順に必要な、名前で有効化した実験的な powerpoint スキル。解決できない場合は、ビルド手順を利用できないことをユーザーに警告し、停止してください。

ディレクトリ構成

.github/skills/experimental/customer-card-render/
├── SKILL.md
├── pyproject.toml
├── references/
│   └── mapping-spec.md
├── scripts/
│   └── generate_cards.py
├── templates/
│   ├── global-style.yaml
│   ├── persona.content.yaml
│   ├── problem.content.yaml
│   ├── scenario.content.yaml
│   ├── use-case-slide1.content.yaml
│   ├── use-case-slide2.content.yaml
│   ├── use-case-slide3.content.yaml
│   └── vision.content.yaml
└── tests/
    ├── fuzz_harness.py
    └── test_generate_cards.py

対応する成果物の種類

成果物の種類	スライドレイアウト
ビジョンステートメント	1 枚のスライド
問題ステートメント	1 枚のスライド
シナリオ	1 枚のスライド
ユースケース	4 枚のスライド（下記参照）
ペルソナ	1 枚のスライド

ユースケースの 4 枚構成レイアウト

各ユースケースは、セクションが異なる連続した 4 枚のスライドに展開されます。

スライド	内容
スライド 1	ユースケースの説明、ユースケースの概要、ビジネス価値、主要ユーザー
スライド 2	副次ユーザー、前提条件、手順、データ要件
スライド 3	機器要件、運用環境、成功基準、ペインポイント
スライド 4	拡張機能、根拠

カードは成果物の種類（ビジョン → 問題 → シナリオ → ユースケース → ペルソナ）の順に並び、各種類の中ではタイトルのアルファベット順に並びます。ユースケースは 4 枚すべてが連続して表示されます（スライド N、N+1、N+2、N+3）。

2 つのコマンドで実行するフロー

手順 1：標準 Markdown からスライド YAML を生成する

python "<customer-card-render-skill-root>/scripts/generate_cards.py" \
  --canonical-dir .copilot-tracking/dt/<project-slug>/canonical \
  --output-dir .copilot-tracking/dt/<project-slug>/render/content

コマンドを実行する前に、読み込んだスキルの場所から <customer-card-render-skill-root> を解決してください。

generate_cards.py CLI リファレンス

フラグ	必須	デフォルト	説明
--canonical-dir	いいえ	<skill-root>/canonical	canonical DT Markdown ファイルを含むディレクトリ
--output-dir	いいえ	<skill-root>/scripts/content	生成された content.yaml ファイルの出力先ディレクトリ
-v, --verbose	いいえ	—	デバッグレベルのログを有効にします

このスクリプトは、--canonical-dir 内の各 Markdown ファイルを読み込み、フロントマターからアーティファクトの種類を判定し、必須セクションを抽出して、content.yaml ファイルを生成します。Vision、Problem、Scenario、Persona の各アーティファクトでは、それぞれ 1 枚のスライドが生成されます。Use Case アーティファクトでは、ユースケースごとに連続した 4 枚のスライドが生成されます。

セクションとフィールドのマッピング仕様、および Use Case の 4 枚構成の詳細については、references/mapping-spec.md を参照してください。

ステップ 2：PowerPoint スキルのパイプラインを使用して PPTX をビルドする

powerpoint スキルを名前で有効にし、次の 3 つの入力を指定してビルドを実行します。

• コンテンツディレクトリ：.copilot-tracking/dt/<project-slug>/render/content
• スタイルパス：.copilot-tracking/dt/<project-slug>/render/content/global/style.yaml
• 出力パス：.copilot-tracking/dt/<project-slug>/render/output/customer-cards.pptx

powerpoint スキルは、Invoke-PptxPipeline.ps1 オーケストレーター、そのパラメーターリファレンス、テンプレートの使用方法、検証、エクスポートオプションを管理し、uv sync による仮想環境のセットアップと依存関係のインストールも自動で行います。このスキルを利用できない場合は、ビルド手順を実行できないことをユーザーに警告し、推測した場所からパイプラインを呼び出さずに停止してください。

DT Coach との統合

dt-coaching-foundation スキルの canonical-deck リファレンスでは、Design Thinking コーチングエージェント向けのオプトイン式ワークフロー統合を提供しています。ユーザーがオプトインすると、コーチングエージェントは各メソッドの終了時にカスタマーカードを作成することを提案します。上記の 2 コマンドのフローは、このワークフローの一部として実行され、.copilot-tracking/dt/ 内のアクティブな DT プロジェクトのスラッグから --canonical-dir と --output-dir が解決されます。

Canonical アーティファクトは DT Coach によって生成され、.copilot-tracking/dt/<project-slug>/canonical/ に保存されます。

テストの実行

cd "<customer-card-render-skill-root>"
uv sync --group dev
uv run pytest tests/

テストでは、解析、テンプレートの選択、YAML の出力、リグレッションを対象とします。tests/fuzz_harness.py ファイルは、OSSF Scorecard への準拠を目的とした Atheris のポリグロット・ファズハーネスです。

コンテンツの忠実性に関する注記：Use Case カード

Use Case カードは、用途に合わせた 3 枚のスライドに分割されており、それぞれに専用のセクションがあります。

• スライド 1：Description、Overview、Business Value、Primary User を使ってユースケースを紹介します
• スライド 2：Secondary User、Preconditions、Steps、Data Requirements を使って実行内容を詳しく説明します
• スライド 3：Equipment Requirements、Operating Environment、Success Criteria、Pain Points、Evidence を使って品質基準を記録します

この構成により、16 個すべての Use Case セクションを、圧縮せずに 4 枚のスライドに読みやすく収められます。各セクションは、適切なスタイルと見出しを備えた独立したテキストボックスに表示されます。

マッピングの詳細については、references/mapping-spec.md を参照してください。

トラブルシューティング

問題	原因	解決策
uv が見つからない	uv がインストールされていない	winget install --id astral-sh.uv -e（Windows）または brew install uv（macOS/Linux）を実行します
uv が Python を見つけられない	Python 3.11 以降が PATH にない	uv python install 3.11 を実行します
テンプレートが見つからない	--canonical-dir に不明なタイプが含まれている	frontmatter の type: フィールドが、サポートされているアーティファクトタイプと一致しているか確認します
出力ディレクトリが空	正規の Markdown ファイルが見つからない	--canonical-dir のパスと、ファイルに --- の frontmatter があることを確認します
生成後に PPTX のビルドが失敗する	PowerPoint スキルがない、または有効化されていない	powerpoint スキルを名前で有効化します。スキルの内容が届かない場合は停止し、ビルド手順を利用できないことを報告します