educates-workshop-authoring

Educates ワークショップ作成スキル

このスキルでは、Educates トレーニングプラットフォーム向けのインタラクティブなワークショップを作成するためのガイダンスを提供します。

ワークショップの初期作成

ユーザーからワークショップの作成を依頼された場合は、次の手順に従います。

1. ワークショップの詳細を確認する

次の情報をユーザーから収集するか、文脈から推測します。

• タイトル：ワークショップの内容を表す、短くわかりやすいタイトル
• 説明：ワークショップの内容を説明する、1～2 文の説明
• 名前：機械可読な識別子（小文字、ハイフン使用可、最大 25 文字、lab- プレフィックスを推奨）

ユーザーがトピックだけを指定し、具体的な値を指定していない場合は、適切なデフォルト値を提案し、続行する前に確認します。

2. ワークショップの場所を決める

次のいずれかを選ぶようユーザーに尋ねます。

• 現在のディレクトリをワークショップのルートとして使用する
• ワークショップ名を使って新しいサブディレクトリを作成する

ディレクトリからワークショップ名を決める場合：

ユーザーが現在の作業ディレクトリを使用することを選んだ場合：

1. ディレクトリ名が命名規則（小文字、ハイフン使用可、最大 25 文字）を満たしているか確認します。注：ディレクトリ名を使用する場合、lab- プレフィックスは推奨ですが必須ではありません。
2. 条件を満たしている場合は、そのディレクトリ名をワークショップ名として使用します。
3. 条件を満たしていない場合は、ワークショップのトピックまたはタイトルから適切な名前を推測します。ただし、ユーザーがすでに名前を明示している場合を除き、続行する前に確認します。

3. ワークショップの要件を決める

ターミナルアプリケーションは常にデフォルトで有効です。わかりやすくするため、必ず enabled: true および layout: split を明示的に指定します。

ワークショップの技術要件に基づいて、追加のセッションアプリケーションについてユーザーに尋ねます。

• エディター：ブラウザーでファイルを編集または表示する必要がありますか？
• Kubernetes アクセス：ユーザーが kubectl コマンドを実行したり、Kubernetes API を操作したりしますか？
• Kubernetes コンソール：クラスターを視覚的に表示すると、ユーザーに役立ちますか？
• Docker：ユーザーがコンテナーをビルドまたは実行しますか？
• イメージレジストリ：ユーザーがコンテナーイメージをプッシュしますか？
• 仮想クラスター：ワークショップで cluster-admin 権限の操作が必要ですか？
• Git サーバー：ユーザーがローカルの Git リポジトリ（CI/CD パイプラインなど）を必要としますか？
• スライド：ワークショップには手順と併せてプレゼンテーションが含まれますか？

ワークショップのトピックから適切なデフォルト値を推測します。たとえば、Kubernetes のワークショップでは、エディター、Kubernetes アクセス、コンソールを有効にする必要があるでしょう。

4. ワークショップの構成を作成する

選択した場所に、次のディレクトリ構成を作成します。

<workshop-root>/
├── README.md                    # Workshop title and description
├── exercises/
│   └── README.md                # Placeholder to ensure directory is preserved
├── resources/
│   └── workshop.yaml            # Educates Workshop definition
└── workshop/
    └── content/                 # Workshop instruction pages (Markdown)

exercises ディレクトリ

ワークショップの初期構成の一部として、必ず exercises/ ディレクトリを作成してください。このディレクトリは、ワークショップのユーザーが作業する場所です。ソースコード、構成ファイル、サンプルデータ、YAML マニフェスト、テンプレート、スタータープロジェクトなど、ワークショップ中に必要となるファイルをここに配置してください。ユーザー向けのファイルをすべて exercises/ の下にまとめることで、ワークショップ環境が整理され、ホームディレクトリが散らかるのを防げます。

ワークショップセッションのコンテナにインポートされたワークショップファイルにこのディレクトリがあると、Educates は特別な動作をします。

• ターミナルの作業ディレクトリ：ワークショップダッシュボードに埋め込まれたターミナルは、ホームディレクトリではなく ~/exercises を現在の作業ディレクトリとして起動します。
• エディターのルートディレクトリ：VS Code エディターはホームディレクトリではなく ~/exercises を開くため、ユーザーにはワークショップに関連するファイルだけが表示され、隠しドットファイルやその他のホームディレクトリ内のファイルに気を取られることがありません。

この特別な動作は、ワークショップセッションの開始時に exercises/ ディレクトリがすでに存在する場合にのみ有効になります。ワークショップの手順で後から作成することはできません。ディレクトリは、公開するワークショップファイルに含まれている必要があります。

重要：ディレクトリには少なくとも1つのファイルが必要です。 ワークショップファイルを Git リポジトリまたは OCI イメージアーティファクトに公開する際、空のディレクトリは保持されません。ディレクトリが含まれるように、README.md を追加し、「このワークショップの演習ファイル」のような簡単な説明や、同様のプレースホルダーを記載してください。ワークショップのソースが Git リポジトリで管理されており、その慣例が適切な場合を除き、.gitkeep ファイルは使用しないでください。

exercises/ ディレクトリは常に推奨されるため、ワークショップの手順で作成する必要はありません。このディレクトリ内のファイルを対象とするクリック可能なアクションでは、ファイルパスに ~/exercises をプレフィックスとして使用してください（例：~/exercises/deployment.yaml）。クリック可能なアクションの例では、参照するファイルにすでにこの規則が適用されています。

5. workshop.yaml を生成する

workshop.yaml の構造とオプションの詳細については、references/workshop-yaml-reference.md を参照してください。

収集した詳細情報に基づいて、resources/workshop.yaml ファイルを生成します。

重要：正しい publish および workshop.files の形式を使用してください。

workshop.yaml には、次のセクションをこの正確な構造で含める必要があります（実際のワークショップ名に置き換えてください）。

spec:
  publish:
    image: "$(image_repository)/{workshop-name}-files:$(workshop_version)"
    files:
    - directory:
        path: .
      includePaths:
      - /workshop/**
      - /exercises/**
      - /README.md
  workshop:
    files:
    - image:
        url: "$(image_repository)/{workshop-name}-files:$(workshop_version)"

重要： spec.content.files は使用しないでください。これは非推奨の形式です。必ず上記の例のように spec.publish と spec.workshop.files を使用してください。ローカルでのワークショップの公開およびデプロイのワークフローをサポートするため、$(image_repository) と $(workshop_version) の変数は、示されているとおりに正確に使用する必要があります。spec.publish.files セクションでは、公開される OCI イメージにパッケージ化するファイルを指定します。指定されたパスのみが含まれるため、イメージを小さく保てます。spec.workshop.files セクションでは、実行時にファイルを取得する場所を指定します。公開済みのイメージではすでに対象が絞り込まれているため、ここで includePaths は必要ありません。spec.workshop.files 配列では、Git および HTTP のソースもサポートされており、複数のエントリを順番に重ねて適用できます。詳細については、workshop YAML リファレンスの「Alternative File Sources」セクションを参照してください。

追加設定：

• metadata.name にワークショップ名を設定します
• 収集した詳細情報に基づいて spec.title と spec.description を設定します
• spec.duration に推定完了時間（例：15m、30m、1h）を設定します
• spec.difficulty に次のいずれかを設定します：beginner、intermediate、advanced、extreme
• enabled: true および layout: split を指定して、必ずターミナルを含めます
• ワークショップに必要な追加のセッションアプリケーションのみを有効にします
• spec.session.namespaces.security.token.enabled は、デフォルトで false に設定します（過去の経緯により、デフォルトでは有効になっています）
• ワークショップで kubectl が必要な場合、または Kubernetes コンソールを使用する場合に限り、spec.session.namespaces.security.token.enabled を true に設定します
• 不要なアプリケーションは省略します（enabled: false を指定して含めないでください）

6. 公開用 GitHub Actions ワークフローを追加する（要求された場合のみ）

ユーザーが GitHub Action を使用した GitHub コンテナレジストリへのワークショップ公開の設定を明示的に依頼しない限り、ワークショップの初回作成時にはこの手順を省略してください。 ワークショップの作成後に、既存のワークショップについてユーザーが公開サポートの追加を依頼した場合も、この手順が適用されます。

この手順は、独自の Git リポジトリに置かれた単独のワークショップにのみ適用されます。複数のワークショップを含むコースの一部である場合は、この GitHub Action を使用しないでください。コースの公開は別の方法で行います。

依頼された場合は、ワークショップのリポジトリに .github/workflows/publish-workshop.yaml ファイルを作成します。ワークフロー設定の詳細、アクションのパラメーター、および公開と workshop.yaml の spec.publish セクションとの関係については、references/workshop-publishing-reference.md を参照してください。

7. ローカル Docker との互換性を追加する（依頼された場合のみ）

ユーザーから、Kubernetes に加えてローカル Docker でもワークショップを動作させたいと明示的に依頼された場合を除き、この手順はスキップしてください。 既存のワークショップに戻って、後からローカル Docker のサポートを追加するよう依頼された場合も、この手順が適用されます。

すべてのワークショップがローカル Docker でのデプロイに対応しているわけではありません。Kubernetes へのアクセス、仮想クラスター、セッションイメージレジストリーを必要とするワークショップや、ワークショップの定義で environment.objects、session.objects、request.objects を使用するワークショップは、ローカル Docker では実行できません。

互換性のあるワークショップでローカル Docker のサポートを依頼された場合、主な変更点は、ワークショップの定義と手順の両方で、すべてのセッションプロキシ URL に ingress_port_suffix データ変数を追加することです。この変数は、標準ポート（Kubernetes）では空文字列になり、標準以外のポート（ローカル Docker）ではポート番号を含むため、追加しても Kubernetes へのデプロイには影響しません。

制約の全一覧、ポートサフィックスを適用する箇所、および既存のワークショップにローカル Docker のサポートを後から追加する方法については、references/local-docker-deployment-reference.md を参照してください。

8. AI アシスタント用の指示ファイルを作成する

次のいずれかに該当する場合、この手順はスキップしてください。

• AI アシスタント用の指示ファイル（例：CLAUDE.md、AGENTS.md）が、すでにワークショップのルートディレクトリーに存在する
• AI アシスタント用の指示ファイルが親ディレクトリーにすでに存在する（ワークショップが、educates-course-design スキルで作成されたコースなど、より大きなプロジェクトの一部であることを示します）

プロジェクトルートに AI アシスタント用の指示ファイルを作成し、今後の AI とのやり取りでプロジェクトの背景情報と使用するスキルが自動的に伝わるようにしてください。Claude Code の場合、このファイルは CLAUDE.md です。他の AI コーディングエージェントでは、別の規約が使われます（例：AGENTS.md）。

指示ファイルには、次の内容を含めてください。

• プロジェクトの概要と説明を記載した README.md への参照
• スキルの参照 — 各スキルを呼び出すタイミング：
  • ワークショップの定義、手順ページ、演習ファイルの作成や変更には、educates-workshop-authoring スキルを使用します
  • このワークショップが後に複数のワークショップから成るコースに組み込まれる場合のコース計画には、educates-course-design スキルを使用します

このファイルは、AI 固有の指示とプロジェクト固有の上書き設定に焦点を絞ってください。README.md にすでに記載されている内容を重複させず、代わりに参照してください。

9. ワークショップの手順を作成する

ワークショップの手順は workshop/content/ ディレクトリーに Markdown ファイルとして配置し、Hugo でレンダリングします。

クリック可能なアクションを使ったガイド形式の手順

デフォルトでは、ワークショップの手順で、コードの表示、実行、変更といったすべての操作をクリック可能なアクションで行う、ガイド形式の体験を提供してください。学習者にターミナルへのコマンド入力や、エディターへの手作業でのコード記述を求めてはいけません。代わりに、すべての操作で適切なクリック可能なアクション（terminal:execute、editor:open-file、editor:replace-matching-text など）を使用してください。これにより、学習者は操作方法ではなく概念に集中できます。ワークショップを依頼した人から別の体験を明示的に求められた場合は、それに応じて調整してください。

学習者がコードを表示、実行、変更する方法や、事前に内容を用意したワークスペースとして exercises/ ディレクトリーを構成する方法を含む、設計思想の全容については、references/workshop-design-principles.md を参照してください。

手順内のクリック可能なアクション

ワークショップの手順では、クリック可能なアクションを使用します。これは、クリックすることでコマンドの実行、ファイルの編集、ワークショップ環境とのやり取りができる特殊なフェンス付きコードブロックです。アクションの種類と詳細な構文については、references/clickable-actions-reference.md を参照してください。

ターミナルコマンドに関する重要な YAML 安全ルール： terminal:execute のクリック可能なアクションを生成するとき、コマンドに YAML で特殊な意味を持つ文字（コロン、ハッシュ記号、中括弧、角括弧など）が含まれる場合、またはコマンドが複数行にわたる場合は、必ず YAML のブロックスカラー構文（command: |-）を使用してください。これにより、YAML パーサーがコマンドを誤って解釈するのを防げます。例：

```terminal:execute
command: |-
  docker run --rm -p 8080:80 nginx:latest
```

また、シェルコマンドでは適切な引用符を使用してください。空白を含むパスを展開する変数は二重引用符で囲み、特殊文字を含む文字列は適切にエスケープする必要があります。詳しくは、クリック可能なアクションのリファレンスにある「YAML Syntax Safety」セクションで、ガイダンスと例を確認してください。

インデントされたテキストを含むエディターアクションに関する重要な YAML 安全ルール： 先頭に空白があるテキスト、つまりすべての行がインデントされているテキストを match、replacement、または text に含むエディターのクリック可能なアクション（editor:select-matching-text、editor:replace-matching-text など）を生成する場合は、必ず YAML のブロックスカラーにインデントインジケーター（例：|2、|4）を使用して、空白を保持してください。これを使用しないと、YAML パーサーによって先頭の空白が削除され、マッチングに失敗したり、置換後のテキストが誤ったインデントで挿入されたりします。例：

```editor:replace-matching-text
file: ~/exercises/deployment.yaml
match: |2
      containers:
      - name: app
        image: myapp:v1
replacement: |2
      containers:
      - name: app
        image: myapp:v2
```

インデントインジケーターを使わずに済む別の方法として、列 1 から始まる外側のコンテキストも含めてマッチ範囲を広げる方法があります。たとえば、インデントされた関数本体だけをマッチさせるのではなく、関数定義の行（例：def my_function():）も含めると、ブロックスカラーの最初の行に先頭の空白がなくなり、通常の | で対応できます。トップレベルの関数には有効ですが、クラスメソッドなど、それ自体がインデントされている構造には役立たない場合があります。インデントインジケーターの詳細については、エディターファイルアクションのリファレンスを参照してください。

テキストプロパティの末尾にある空行に関する重要な YAML 安全ルール： エディターのクリック可能なアクションの text または replacement プロパティが 1 行以上の空行で終わる場合、その空行は 2 つの段階で失われる可能性があります。YAML の既定の「clip」チョンピングによりブロックスカラー値の末尾の改行が削除され、Hugo の Markdown プロセッサーによりコードフェンス末尾の空行が削除されるためです。末尾の空行を保持するには、次の両方を行う必要があります。ブロックスカラーに + キープチョンピングインジケーター（| ではなく |+）を使用し、YAML の最後のプロパティとして eot: true を追加します。例：

```editor:insert-lines-before-selection
file: ~/exercises/app.py
text: |+
  # --- Section boundary ---

eot: true
```

|+ は YAML に末尾の改行を保持するよう指示し、クリック可能なアクションでは意味を持たない eot: true プロパティによって、Hugo が削除してしまうコードフェンス末尾のコンテンツに空行が含まれないようにします。詳しくは、クリック可能なアクションのリファレンスにある「Trailing blank lines in text properties」セクションを参照してください。

ターミナルの作業ディレクトリの追跡

exercises/ ディレクトリが存在する場合、各ターミナルセッションはホームディレクトリではなく、現在の作業ディレクトリを ~/exercises として開始します。ワークショップの手順を作成する際は、手順のすべての時点で各ターミナルの現在の作業ディレクトリを必ず追跡してください。terminal:execute アクション内の cd コマンドは、そのターミナルで以降に実行されるすべてのコマンドの作業ディレクトリを変更します。

これを誤ると、コマンドで誤ったファイルパスを参照してしまいます。次のいずれかを行ってください。

• 作業ディレクトリを追跡し、正しい相対パスを使用します。 たとえば、ターミナルが ~/exercises にあり、~/exercises/deployment.yaml にアクセスする必要がある場合は、deployment.yaml を使用します。前の手順で cd ~/exercises/myapp を実行した場合は、deployment.yaml に ../deployment.yaml を指定するか、フルパスを使用する必要があります。
• 曖昧さを避けるために絶対パスを使用します。 たとえば、現在のディレクトリにかかわらず、常に ~/exercises/deployment.yaml を使用します。

ワークショップでターミナル分割レイアウト（2つのターミナル）を使用する場合は、各ターミナルの作業ディレクトリを個別に追跡してください。一方のターミナルでの cd は、もう一方のターミナルには影響しません。

ダッシュボードタブの表示

ワークショップダッシュボードでは、画面右側に一度に1つのタブだけが表示されます（左側にはワークショップの手順が表示されます）。セッション開始時には、デフォルトで「Terminal」タブが表示されます。ユーザーはタブのヘッダーをクリックするか、dashboard:open-dashboard のクリック可能なアクションを使ってタブを切り替えます。

手順を作成する際には、特定のアクションによって表示されるタブが暗黙的に切り替わることがあるため、この点が重要です。terminal:execute アクションを実行すると「Terminal」タブに切り替わり、ユーザーが表示していた他のタブ（Web アプリケーションのダッシュボードなど）は非表示になります。ワークショップでカスタムダッシュボードタブ（セッションプロキシ経由でアクセスする Web アプリなど）を使用する場合は、ターミナルコマンドの実行後にユーザーがそのタブに戻れるよう、明示的に案内して結果を確認できるようにしてください。

ダッシュボードタブは URL バーのない iframe です。ユーザーはタブが参照している URL を確認したり変更したりできません。また、コンテンツは iframe に埋め込まれるため、埋め込まれた Web アプリケーションのページタイトルもブラウザー上のどこにも表示されません。ブラウザーのタブ／ウィンドウのタイトルは iframe のコンテンツではなく、最上位の親ページによって決まります。ダッシュボードタブに表示する内容を変更するには、新しい url を指定して dashboard:reload-dashboard を使用します。コンテンツを再読み込みせずにタブを表示するだけの場合は、URL を指定しない dashboard:reload-dashboard ではなく、dashboard:open-dashboard を使用してください。手順の途中でタブの URL を変更するワークショップでは、spec.session.dashboards で事前定義するのではなく、dashboard:create-dashboard を使ってタブを動的に作成することをおすすめします。そうすることで、最初の URL をその場で確認できます。

ワークショップの手順でタブを切り替える際の詳しいパターンと例については、references/workshop-dashboard-reference.md を参照してください。

手順内のデータ変数

ワークショップの手順では、セッション固有の値をハードコードせず、データ変数を使ってパラメーター化してください。Educates は、セッションの名前空間、イングレスドメイン、セッションホスト名など、さまざまなコンテキスト固有の値に対応するデータ変数を提供しています。Hugo の param ショートコードを使って挿入します。

Deploy the application to the `{{< param session_namespace >}}` namespace.

データ変数はクリック可能なアクション内でも使用できます。

```terminal:execute
command: kubectl get pods -n {{< param session_namespace >}}
```

クリック可能なアクション内のターミナルコマンドでは、代わりに同等の大文字の環境変数（例：$SESSION_NAMESPACE）を使用することもできます。これらの変数はターミナルシェルで自動的に設定されています。使用可能なデータ変数の一覧と、使用できるコンテキストについては、references/data-variables-reference.md を参照してください。

ページ構成

各ページには、少なくとも title プロパティを含む YAML フロントマターが必要です。

---
title: Page Title
---

This is the introductory paragraph for the page. It appears immediately
after the frontmatter with no heading.

## First Section

Content for the first section...

## Second Section

Content for the second section...

コンテンツのガイドライン：

• ページのコンテンツには標準の Markdown を使用してください
• レベル 1 の見出し（#）は使用しないでください。フロントマターの title がページのヘッダーとして自動的に生成されます
• フロントマターの直後から導入の段落を始めてください
• 追加のセクションには、レベル 2 の見出し（##）以下を使用してください
• 重要な情報を強調するには、アドモニションショートコードを使用してください。 注意事項には {{< note >}}、警告には {{< warning >}}、重大な警告には {{< danger >}} を使用します。構文と使用方法については、references/hugo-shortcodes-reference.md を参照してください。
• プラットフォームではなく、ワークショップのトピックに焦点を当ててください。 ワークショップの手順では、Educates の仕組みではなく、対象となる内容を教えてください。ワークショップでプラットフォーム固有の設定（たとえば、デプロイ済みサービスにアクセスするためのセッションプロキシの設定、イングレスの構成、データ変数の使用）が必要な場合は、Educates の内部構造に触れず、演習の自然な手順として提示してください。「Educates の設定方法を学びます」や「Educates ではこのようにイングレスを処理します」といった説明は、Educates プラットフォーム自体の使い方がワークショップの主題である場合を除き、避けてください。概要、まとめ、学習目標では、ワークショップを支えるインフラではなく、トピックについて参加者が学ぶ内容を説明してください。

ファイル名の規則

ページの順序を示すには、数値のプレフィックスを使用してください：nn-page-name.md

推奨される構成：

• 00-workshop-overview.md - 導入と目標
• 01-first-topic.md - 最初の解説ページ
• 02-second-topic.md - 以降、主要コンテンツに合わせて番号を増やします
• 99-workshop-summary.md - まとめと次のステップ

00- は概要、99- はまとめ用に確保してください。主要な解説ページは 01- から始め、番号を増やしてください。

ページバンドル

シンプルなページには単一の .md ファイルを使用してください。ページに埋め込みの画像がある場合は、ページバンドルを使用してください。

workshop/content/
├── 00-workshop-overview.md
├── 01-first-topic/
│   ├── index.md
│   └── diagram.png
├── 02-second-topic.md
└── 99-workshop-summary.md

ページバンドルは、index.md と関連アセット（画像など）を含むディレクトリです。ワークショップのページに画像を含める方法の詳細については、references/images-in-workshop-pages.md を参照してください。

10. ワークショップ定義を確認する

resources/workshop.yaml を生成したら、次の重要な項目を確認してください。

必須セクションが存在すること：

• spec.publish セクションに image フィールドと files フィールドがある
• spec.publish.files で includePaths を使用し、/workshop/**、/exercises/**、/README.md のみを選択している
• spec.workshop セクションに files 配列がある
• spec.publish.image と spec.workshop.files の両方で、$(image_repository) と $(workshop_version) 変数を使用している

非推奨の形式を使用していないこと：

• spec.content.files が存在しない（代わりに spec.workshop.files を使用する）

アプリケーションの設定：

• ターミナルに enabled: true と layout: split が含まれている
• 必要なアプリケーションのみを含めている（無効なアプリケーションは記述せず省略する）
• Kubernetes へのアクセスが必要な場合を除き、spec.session.namespaces.security.token.enabled を明示的に false に設定している

11. ワークショップの手順を確認する

ワークショップの手順ページを生成した後、以下を確認します。

ターミナルの作業ディレクトリが正しいこと：

• 各ターミナルの初期作業ディレクトリが把握されている（exercises ディレクトリが存在する場合は ~/exercises、それ以外の場合は ~）
• terminal:execute アクション内のすべての cd コマンドを追跡し、各手順後の作業ディレクトリが把握されている
• ターミナルコマンド内のすべての相対ファイルパスが、手順のその時点の作業ディレクトリに対して正しい
• ターミナルを分割して使用する場合、各ターミナルの作業ディレクトリを個別に追跡している

ファイルパスの一貫性：

• editor のクリック可能なアクションで使用するファイルパスには、適切な場合に ~/exercises のプレフィックスが付いている
• 説明文で参照しているファイルパスが、クリック可能なアクションで使用するパスと一致している

ダッシュボードタブの表示状態：

• ターミナル以外のダッシュボードタブ（ウェブアプリケーションなど）を表示している手順の後に terminal:execute アクションを実行する場合、適切なタブに戻るよう手順で案内している。コンテンツの更新が不要な場合は dashboard:open-dashboard、コンテンツの再読み込みや URL の変更が必要な場合は dashboard:reload-dashboard を使用する
• ターミナルの作業ディレクトリと同様に、手順全体を通じて表示中のダッシュボードタブを追跡している
• タブを表示することだけを目的として、URL を指定せずに dashboard:reload-dashboard を使用していない。その目的には dashboard:open-dashboard を使用する
• ワークショップ中にダッシュボードタブの URL を変更するために dashboard:reload-dashboard を使用する場合、初期ダッシュボードは spec.session.dashboards で事前定義せず、手順内で dashboard:create-dashboard を使って作成している。これにより、読者に初期 URL が表示される

エディターアクション内の YAML 構文：

• match、replacement、text の内容が先頭のスペースで始まる editor:select-matching-text、editor:replace-matching-text などのアクションでは、YAML ブロックスカラーのインデント指示子（|2、|4 など）を使用している。または、1 列目から始まる周囲のコンテキストも含めて一致範囲を広げ、通常の | で済むようにしている
• text または replacement プロパティが末尾の空行で終わるエディターのクリック可能なアクションでは、|+ のキープチョンピング指示子を使用し、YAML と Hugo によって空行が削除されないよう、最後の YAML プロパティとして eot: true を含めている

ガイド付きの手順：

• コードの閲覧にはすべてエディターのクリック可能なアクション（editor:open-file、editor:select-matching-text）を使用している。通常のコードブロックや cat などのターミナルコマンドは使用していない
• コマンドの実行にはすべて terminal:execute のクリック可能なアクションを使用している。学習者にコマンドを手入力させていない
• コードの変更にはすべてエディターのクリック可能なアクション（editor:replace-matching-text、editor:append-lines-after-match、editor:insert-lines-before-match など）を使用している。学習者にファイルを手作業で編集させていない
• workshop:copy または workshop:copy-and-edit は、データ変数では対応できず、学習者ごとに内容をカスタマイズする必要がある場合にのみ使用している

内容の焦点：

• ワークショップの概要とまとめでは、Educates プラットフォームではなく、学習内容を説明している
• 学習目標は、トピックについてユーザーが学ぶ内容に焦点を当てている
• プラットフォーム固有の手順（プロキシ、イングレス、データ変数）は、Educates の内部実装に言及せず、演習の自然な一部として提示している

12. 計画ドキュメントの更新（コースのワークショップのみ）

ワークショップが計画ドキュメントのあるコースの一部である場合（つまり、ワークショップ計画を含む planning/ ディレクトリが存在する場合）、実装中に行った重要な変更を計画ドキュメントにも反映する必要があるか確認してください。後続のワークショップの計画を正確な情報に基づいて始められるよう、ワークショップ計画を実際の内容に合わせておくことが目的です。

更新する内容：

• ページの変更：ページのトピックやタイトルを変更した場合は、新しい内容に合わせてページファイルの名前を変更し、ワークショップ計画のページ一覧も更新してください。
• アプローチの変更：全体的なアプローチを変更した場合（手法の切り替え、演習の簡略化や再構成、別のライブラリやツールの選択など）は、当初の計画ではなく、実際に構築した内容を説明するようワークショップ計画を更新してください。
• ファイル名の変更：ページファイルの名前を変更した場合は、他のワークショップページや計画ドキュメントに古いファイル名への参照が残っていないか確認してください。
• 連続するワークショップへの影響：連続するワークショップでは、次のワークショップの計画や実装が、変更内容を参照していないか確認してください。「前回のワークショップとのつながり」セクション、演習、物語上の導入などで、当初のアプローチを前提としている場合があります。

educates-course-design スキルを使ってこれらの更新を行ってください。このスキルは計画ドキュメントの形式を管理し、変更が適切な構成に沿うようにします。重要なのは、ワークショップ計画に当初の草案ではなく、実際に構築された設計が反映されていることです。

リファレンスガイド

特定のトピックについて詳しくは、以下を参照してください。

• ワークショップ設計の原則 - ガイド付き体験の理念、手動入力をさせないルール、学習者がコードをどのように確認、実行、変更するべきかについての指針
• Workshop YAML リファレンス - workshop.yaml の構造とオプションの全容
• ワークショップページでの画像 - ページバンドルと静的アセットを使用して画像を含める方法
• クリック可能なアクションのリファレンス - クリック可能なすべてのアクションタイプの一覧、YAML 構文の安全性に関するガイダンス、カテゴリ別リファレンスへのリンク（references/clickable-actions/）
• ワークショップツールのリファレンス - JSON/YAML の処理、Kubernetes の管理、コンテナの操作、負荷テストなど、ワークショップ環境で利用できるコマンドラインツール
• Kubernetes アクセスのリファレンス - Kubernetes アクセスを伴うワークショップ向けの名前空間の分離、セッションの名前空間の参照、Pod セキュリティポリシー
• データ変数のリファレンス - ワークショップの手順、ターミナルコマンド、ワークショップ定義をパラメーター化するデータ変数の完全な一覧
• ワークショップダッシュボードのリファレンス - ダッシュボードのレイアウト、単一タブの表示動作、ワークショップの手順でユーザーをタブ間に誘導するパターン
• ワークショップイメージのリファレンス - 事前構築済みの JDK イメージや Conda イメージなど、ワークショップ向けのコンテナイメージの選択
• Java 言語のリファレンス - Java ワークショップ向けの JDK イメージの選択、Maven/Gradle のビルドコマンド、プロジェクトの構成、Spring Boot のパターン
• Python 言語のリファレンス - Python ワークショップ向けの Python バージョン管理、uv/pip によるパッケージのインストール、プロジェクトの構成、Web フレームワークのパターン
• ワークショップセットアップのリファレンス - ワークショップコンテナのセットアップスクリプト、環境変数、バックグラウンドサービス、ターミナルのカスタマイズ
• Hugo ショートコードのリファレンス - 警告表示（note、warning、danger）、パスウェイの条件付きレンダリング、ワークショップの手順で使うカスタムショートコード
• セッションオブジェクトのリファレンス - セッションごとの Kubernetes リソースの事前作成、共有環境オブジェクト、リクエストオブジェクト、ワークショップコンテナのリソース設定
• ワークショップ公開のリファレンス - Educates の publish-workshop GitHub Action を使い、スタンドアロンのワークショップを GitHub コンテナレジストリに公開するための GitHub Actions ワークフローの追加方法。初回作成時か、後から既存のワークショップに追加する場合かを問わず、ユーザーからワークショップの公開設定を求められたら参照してください。
• ローカル Docker デプロイのリファレンス - Kubernetes に加えてローカル Docker でも実行する必要があるワークショップに対する制限と必須の変更。初回作成時か、後から既存のワークショップに適用する場合かを問わず、ユーザーからローカル Docker との互換性を求められたら参照してください。
• ローカルクラスターへのデプロイのリファレンス - educates create-cluster で作成したローカル Educates クラスターで、ワークショップを公開、デプロイ、更新、削除する方法。ユーザーからローカルクラスターへのワークショップの公開またはデプロイを求められたら参照してください。これらのコマンドを自動的に実行しないでください。ローカルクラスター内のワークショップの管理をユーザーが明示的に求めた場合にのみ実行してください。

スキルのバージョン

スキルのバージョンを尋ねられた場合は、VERSION.txt ファイルを読み、その内容をユーザーに伝えてください。

ヘルプを利用する

詳しくは、Educates のドキュメントをご覧ください：https://docs.educates.dev/