Communitygithub.com

wwwyo/syokan

syokan — LLM がリッチな UI を召喚します。JSON の呪文を唱えれば、生きたインターフェースが現れます。設計上エフェメラル(一時的)です。

syokan とは?

syokan (召喚) は、LLM エージェントが JSON エンベロープを POST することでリッチな UI を動的に生成できるスキルです。ユーザーが「syokan X」と指示すると、エージェントはスキーマ駆動のビューレイヤーにデータをマッピングし、 `syokan` CLI 経由でサーバーに送信します。ビューはエフェメラルで永続性の保証はありませんが、テンプレート機能により再現可能なレイアウトは保存・再利用できます。対応プラットフォームは CLI ツールであり、 `syokan catalog` で利用可能なコンポーネントとプロパティを確認し、 `syokan snapshot.json` などでビューを作成します。ローカルファイルも自動ラップして表示でき、ファイル保存時にビューが自動更新されるため、開発やレビュー作業に適しています。

対応✓Claude Code~Codex CLI~Cursor
npx skills add wwwyo/syokan

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

syokan は何をしますか?

syokan(召喚、"summon")は動詞です — LLM がリッチな UI を召喚します。 ユーザーが「syokan X」(日本語では「X を syokan」)と言ったら、それはそのデータをビューとして召喚するリクエストです。内部ではスキーマ駆動のビューレイヤーが動作しています。JSX を書く代わりに、JSON の呪文 — カタログコンポーネントのツリー — を話すと、syokan がそれを定義済みコンポーネントでレンダリングします。 あなたの仕事は、データをエンベロープにまとめて syokan に POST することです。 文章中では、syokan を裸の他動詞として使ってください(「do syokan」や「syokan する」とは決して使わないでください — syokan は単独で成立します)。

syokan がまだインストールされていない場合(syokan --help が失敗する場合)、またはユーザーが「onboarding」「set it up」「初めて使う」などと言った場合は、references/onboarding.md の手順に従って最初のスナップショットまで導いてください。環境を変更する操作(インストールなど)を静かに実行しないでください。インストールされていないことを報告し、実行前にユーザーの承認を得てください(自分でインストールしてはいけません)。

絶対条件

  • スナップショットはエフェメラルです: ポストされたスナップショットには永続性の保証はありません。再構築可能で一時的なデータ(今日の RSS、進行中のレビューなど)のみを配置してください。再利用するレイアウトについては、テンプレートを保存して再現してください(テンプレートは永続化されます。以下の「再現性のためのテンプレート」を参照)。
  • JSON のみ: サーバーは JSON エンベロープしか受け付けません。生の Markdown やプレーンテキストは拒否されます。散文を表示するには、MarkdownDoc または PlainText ノードでラップしてください。
  • 厳密なスキーマ: props は厳密に検証されます。スキーマにないキーは拒否されます。余計なキーを発明しないでください。
  • リーフノードは子を持てません: Stack と Card のみが子を受け入れます。リーフノードに子を付けると取り込み時に拒否されます。

構成から表示まで

  1. syokan catalog で利用可能なタイプと props を確認します(以下の「カタログ」を参照)。
  2. 表示したいデータをそれらのコンポーネントにマッピングします。最上位は通常、コンテナー(Stack など)で、アイテムを垂直に積み重ねます。
  3. エンベロープ JSON に変換します(以下の「エンベロープの形状」を参照)。必須なのは root だけです。
  4. CLI でポストします(以下の「ポスト」を参照)。成功するとビュー URL が表示されます。

以前に似たようなビューを構築したことがある場合は、ゼロから始めず、保存済みテンプレートをベースにしてください(以下の「再現性のためのテンプレート」を参照)。

エンベロープの形状

POST ボディには以下の項目のみを含めることができます。 id、createdAt、url は絶対に含めないでください。サーバーが割り当てます。

{
  "root": { "type": "Stack", "props": {}, "children": [ /* カタログノード; 完全な例は references/examples.md を参照 */ ] }, // 必須。ビューツリー
  "title": "今日のRSS",                                // オプション。リストとビューヘッダーに表示されます
  "metadata": { "source": { "label": "daily-rss" } },   // オプション。出典ラベル
  "schemaVersion": 1,                                    // オプション。サーバーが補完します
  "idempotencyKey": "rss-2026-06-28"                     // オプション。このビューに名前を付け、後で更新しても重複しないようにします
}

metadata.source は label 以外のキーも保持できます。url や fetchedAt を追加しても構いません(例:{ "label": "gh-review", "url": "https://example.com/..." })。

日次や繰り返しのビューの場合は、idempotencyKey に日付などを含めてください。syokan CLI が残りを処理します。まずそのキーをターゲットにし、既存のビューがなければ新しいビューを作成します。したがって、最初のポストでビューが作成され、それ以降同じキーでポストすると、同じビューがその場で更新され、重複しません。最初のポストかどうかを自分で追跡する必要はありません。(CLI ではなく HTTP API を直接呼び出す場合:POST /api/snapshots は常に作成してキーをタグ付けします。PUT /api/snapshots は既存のキーをターゲットにし、存在しない場合は 404 を返します — 作成時に存在しない場合のエンドポイントはないため、CLI はまず PUT を試し、404 の場合に POST にフォールバックします。)

カタログ

利用可能な type とその props 定義は syokan catalog から取得してください(決して md に転記せず、毎回ここから取得してください)。

出力は { "items": [{ "type", "props", "childrenTypes" }] } です。

  • props: そのタイプの props(JSON Schema 形式)。required / enum / format(httpUrl は uri、Time.datetime は date-time)/ additionalProperties:false(未知のキーは拒否されます)を指定されたとおりに満たしてください。
  • childrenTypes: null は子を受け入れるコンテナー、[] は子を受け入れないリーフ、[..] はリストされたタイプのみが子になれることを意味します。

コンポーネントを組み合わせた完全な例については、references/examples.md を参照してください。

ポスト

組み立てたエンベロープをファイルまたは標準入力で渡します。成功するとビュー URL が標準出力に表示されます(syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan)。

その他のコマンド、サブコマンド、環境変数、終了コードについては syokan --help --json を参照してください。タイプと props については syokan catalog を参照してください。

ローカルファイルのプレビュー

ローカルファイルの場合、syokan <path> が最短ルートです — ファイル自体を syokan します。エンベロープ JSON はそのままポストされます。それ以外(markdown / log / txt / json など)は、自動的にライブ FileDoc にラップされます。CLI は絶対パスに解決してサーバーに渡し、サーバーがコンテンツを読み込み、拡張子からフォーマットを推測します(.md/.markdown → markdown、.json → code、その他 → text)。ビューが開いている間はファイルの編集を追跡します(再ポスト不要)。

syokan notes.md   # markdown をレンダリング。保存するたびにビューが更新されます
syokan app.log    # 等幅フォントで成長するログを表示します

複数のファイルを 1 つのビューにまとめたり、Heading などのノードと混在させたい場合は、自分で FileDoc ノードを配置してください(props: path、絶対パスのみ。FileDoc は読み取りと変更追跡を処理します)。

逆に、ファイルの内容を静的に固定して表示したい場合(追跡不要、または内容を変換する場合)は、ボディを MarkdownDoc / PlainText / Code ノードに配置してください。jq --rawfile を使えば JSON エスケープを気にせずにストリーム入力できます。

jq -n --rawfile body README.md \
  '{title:"README.md", root:{type:"Stack",props:{},children:[{type:"MarkdownDoc",props:{body:$body}}]}}' \
  | syokan

再現性のためのテンプレート

お気に入りのビューを毎回ゼロから作り直さないでください。syokan にテンプレートとして保存し、再利用してください。 テンプレートとは「保存されたエンベロープそのもの」です。スケルトンに {{...}} のようなマーカーを配置し、自分で埋めることもできます。

一致するテンプレートが存在する場合は、ゼロから構築せず、リストから ID を見つけて取得し、データを入れ替えてポストしてください。保存する価値のある新しいビューを作成したら、それを保存し、次回はそれを使って再現してください。サブコマンドの構文(templates list|add|get|rm)については、syokan --help --json を参照してください。

関連スキル