skills-docs

スキルドキュメントシステム

人間が読めるウェブドキュメントと、LLM エージェントによる利用の両方に対応する単一の信頼できる情報源です。

アーキテクチャ

skills/skills/{skill-name}/
  SKILL.md                    # Overview + quick start (LLM entry point)
  references/
    {name}.md                 # Reference, tutorial, how-to, or explanation

1 つのソースから 2 つのビルドターゲットを生成します。

• ウェブドキュメント：Telecine は skills/skills/ を直接読み込み、MDX と規約に基づくコンポーネントマッピングを使ってレンダリングします
• LLM スキル：generate-skills.ts は人間向けのメタデータを除去し、API メタデータを文章に変換して、skills/skills-generated/（gitignore 対象のビルド成果物）に出力します

作成ワークフロー

1. skills/skills/ のソースファイルを編集します
2. ウェブ上でプレビューします。telecine はソースを直接読み込むため、ビルド手順は不要です
3. LLM ファイルを生成します：npx tsx scripts/generate-skills.ts
4. スキルのリモートリポジトリにプッシュします：./scripts/push-skills [--branch name]

LLM が利用できるリポジトリに公開する場合のみ、手順 3～4 が必要です。開発中は、ウェブプレビューですぐに変更を確認できます。

skills/skills-generated/ は編集しないでください。ビルドのたびに上書きされます。

Frontmatter クイックリファレンス

SKILL.md ファイル

フィールド	必須	生成後も保持
name	はい	はい
description	はい	はい
license	いいえ	はい
metadata（author、version）	いいえ	はい

参照ファイル

フィールド	必須	生成後も保持	用途
title	はい	はい（name として）	表示名
description	はい	はい	簡単な説明
type	はい	いいえ	reference | tutorial | how-to | explanation
nav	いいえ	いいえ	ツリー型サイドバー：parent、priority、related
topic	いいえ	いいえ	トピック別に分類されたサイドバーのカテゴリ
order	いいえ	いいえ	トピックグループ内の並び順
track	いいえ	いいえ	学習パスの識別子
track_step	いいえ	いいえ	学習パス内の位置
track_title	いいえ	いいえ	トラックナビゲーションに表示するタイトル
prerequisites	いいえ	いいえ	必読の参照資料
next_steps	いいえ	いいえ	次に読む資料の候補
api	いいえ	文章に変換	構造化された API メタデータ
sections	いいえ	いいえ	複数のウェブページに分割

フィールドの詳細については、frontmatter.md を参照してください。

重要な制約

YAML パーサーの制限

生成スクリプトでは、以下のみをサポートする独自実装の YAML パーサー（scripts/generate-skills.ts）を使用しています。

• トップレベルのスカラー値フィールド（key: value）
• 1 階層のオブジェクトのネスト（key:\n subkey: value）
• インデント 4 つのオブジェクトの配列（ - name: value）
• 配列項目内でインデント 6 つ以上のオブジェクトプロパティ

サポート対象外（エラーを表示せずに誤った出力が生成されます）：

• 複数行文字列（| または > のブロックスカラー）
• インラインのフローシーケンス（[a, b, c]）
• YAML コメント
• 3 階層を超えるネスト
• 引用符で囲まれたキー

frontmatter を変更した後は、必ずローカルで生成をテストしてください。

npx tsx scripts/generate-skills.ts
# Inspect skills/skills-generated/ to verify output

Sections と見出しの連動

sections frontmatter は、heading フィールドを使って Markdown の H2 見出しを参照します。完全一致が必要です。H2 を変更する場合は、対応する sections[].heading も更新してください。

sections:
  - slug: tutorial
    heading: Video Tutorial    # Must match "## Video Tutorial" in body

ナビゲーションの親パス

nav.parent は、サイドバーツリーを作成するために / 区切りのパス（スラッシュの前後にスペースを含む）を使います。

nav:
  parent: "Elements / Media"   # Creates: Elements > Media > this page

親パスのつづりを間違えると、エラーを表示せずにノードが孤立します。新しいパスを作成する前に、既存の参照先で確立済みのパスを確認してください。

レンダリング規約

ウェブレンダラーは Markdown のパターンを検出し、インタラクティブなコンポーネントに変換します。執筆の詳細については、conventions.md を参照してください。

パターン	ウェブでのレンダリング	LLM 出力
```html live	インタラクティブプレビュー＋フィルムストリップ	通常のコードブロック
```mermaid	Mermaid 図をレンダリング	通常のコードブロック
> **Note:** ...	青色のコールアウトボックス	標準の引用ブロック
> **Warning:** ...	金色のコールアウトボックス	標準の引用ブロック
属性／型／説明のテーブル	拡張された PropertyDoc スタイル	標準のテーブル
チュートリアル内の ### Step N:	ステップインジケーターのスタイル	標準の見出し
[references/X.md](references/X.md)	React Router のリンク	相対リンク
api のフロントマター	H1 の後にカード形式の ApiReference を表示	H1 の後に文章形式のリストを表示

生成時の変換

generate-skills.ts が各ソースファイルに対して行う処理：

• title → 出力フロントマターの name になる
• description、license、metadata → 保持される
• nav、track、track_*、prerequisites、next_steps、type、topic、order、sections → 削除される
• api → 文章形式に変換され、H1 の後に挿入される：

## Attributes
- **src** (string) (required) - URL or path to video source
- **volume** (number, default: 1.0) - Audio volume

## Properties
- **sourceIn** (string) - Absolute start time

## Methods
- **play()** - Start playback
  - Returns: void

## Functions
- **createRender(client, payload)** - Create a new render job
  - Returns: CreateRenderResult

Markdown 本文は変更されずに保持されます。

API メタデータの型

api フロントマターは、異なる API サーフェスの型に対応する 4 つのサブキーをサポートします。

• attributes：HTML 要素の属性（例：<ef-video src="...">）

  • 用途：カスタム要素、ウェブコンポーネント
  • フィールド：name、type、required、default、description、values

• properties：React コンポーネントの props（例：<Preview className="...">）

  • 用途：React コンポーネント、TypeScript インターフェース
  • フィールド：name、type、required、default、description、values

• methods：オブジェクトまたは要素のインスタンスメソッド（例：element.play()）

  • 用途：インスタンスに存在するメソッド、DOM API
  • フィールド：name、signature、description、returns

• functions：単独でエクスポートされる関数（例：createRender(client, payload)）

  • 用途：SDK 関数、ユーティリティ関数、トップレベルのエクスポート
  • フィールド：name、signature、description、returns

4 つの型はいずれもウェブ上ではカードグリッドとしてレンダリングされ、LLM が利用する際はインデント付きの文章形式のリストに変換されます。

主なファイルの場所

Skills のコンテンツ

• skills/skills/ — ソースファイル（ここを編集）
• skills/skills-generated/ — ビルド成果物（編集禁止、gitignore 対象）
• skills/BUILD.md — ビルドプロセスのドキュメント

ビルドパイプライン

• scripts/generate-skills.ts — 生成スクリプト
• scripts/push-skills — skills の生成とリモートへのプッシュ

ウェブレンダラー（telecine）

• telecine/services/web/app/utils/skills.server.ts — 読み込み、ナビゲーションの構築、セクションの抽出
• telecine/services/web/app/utils/skills-mdx-components.tsx — 規約に基づく MDX コンポーネント
• telecine/services/web/app/routes/skills/reference-detail.tsx — リファレンスページ
• telecine/services/web/app/routes/skills/skill-detail.tsx — スキル概要ページ＋サイドバーツリー
• telecine/services/web/app/components/skills/ApiReference.tsx — API リファレンスカード
• telecine/services/web/app/components/skills/OnThisPage.tsx — H2／H3 から自動生成される目次

レガシードキュメント（コンテンツ移行元）

• telecine/services/web/app/content/docs/ — コンテンツの参照元となる MDX ファイル
• telecine/services/web/app/components/docs/ — レガシーコンポーネント（Demonstration、PropertyDoc）

レンダラーを変更する場合

規約ベースのレンダリングは skills-mdx-components.tsx にあります。

• SkillsPreBlock — data-meta 属性（remarkCodeMeta プラグインが設定）を使って html live を検出します
• LiveDemo — @editframe/react の Preview/FitScale/FocusOverlay/Filmstrip 内に生の HTML をレンダリングします
• SkillsTable — 属性／型／説明の列見出しを検出し、拡張スタイルを適用します
• SkillsBlockquote — 注記／警告の接頭辞を検出し、コールアウトボックスを表示します
• getSkillsMDXComponents(skillName, api?) — コンポーネントのマッピング一式を返します。api が指定されている場合は、H1 をラップして ApiReference を挿入します

skill-detail.tsx と reference-detail.tsx は、どちらも共有コンポーネントマッピングを使用します。

ナビゲーションは skills.server.ts で構築します。

• getSkillNavTree() — nav.parent のパスからツリーを構築します
• getSkillNav() — topic フィールドからトピックグループを構築します
• 型の順序：チュートリアル → ハウツー → 解説 → リファレンス

コンテンツガイドライン

長さの目安

種類	目安	焦点
reference	60～100行	属性、基本的な使い方、一般的なパターン
tutorial	約90行	html live デモを使った手順、導入は最小限
how-to	20～40行	1つのタスク、操作のみ、理由の説明なし
explanation	60～80行	概念を掘り下げた説明、コード／設定なし

執筆の原則

1つのドキュメントにつき1つのモードにします。 各ファイルは1つの type に適合させます。内容が別のモードに該当する場合は、含めるのではなくリンクします。チュートリアルではアーキテクチャを説明しません。リファレンスには理由の説明を含めません。ハウツーでは概念を教えません。

ファイル間で内容を繰り返しません。 ある概念を1つのリファレンスで説明している場合は、ほかのリファレンスからリンクします。同じドキュメント内で意味が重複する文がある場合は、どちらかを削除します。

中立的で技術的な表現を使います。 指示や比較による批評ではなく、プラットフォームの制約と結果を説明します。

• 「ネイティブ再生ではファイル全体のダウンロードが必要です」。「ファイル全体をダウンロードする必要があります」ではありません
• 「ファイルを直接再生すると、次のような制約があります」。「従来のワークフローは遅いです」ではありません
• 絶対的な表現には条件を付けます。「通常は数秒以内」。「即座に」ではありません

実装ではなく効果を説明します。 内部の仕組みではなく、ユーザーに見える内容を説明します。「プレーヤーはリアクティブで、段階的に動作します」。「バックエンドがファイルを分割します」ではありません。

説明するのではなく、実演します。 html live ブロックを使って実例を示します。チュートリアルの各ステップとハウツーの解決方法には、動作するデモを用意します。リファレンスファイルでは、属性の一覧だけでなく、基本的な使い方を示します。

実際のアセットを使います。 デモには https://assets.editframe.com/ の URL を使います（例：bars-n-tone.mp4）。