add-concept

グラフに概念を追加する

各ノードは、plugins/runpod/skills/runpod-usage/concepts/ にある1つの YAML ファイルです （以下では concepts/ と呼びます）。形式、種類、関係のタイプ、文体は concepts/README.md で定義されています。作成前に読んでください。この スキルで説明するのは手順であり、形式ではありません。

すべてのファイルは一般公開を前提としています。記載する内容はすべて、お客様に見せても問題がなく、公開ソースで裏付けられている必要があります。バリデーターがこれをチェックします。

1. すでに存在しないか確認する

何かを作成する前に、ID、名前、別名を検索します。

grep -ril "<term>" plugins/runpod/skills/runpod-usage/concepts/
cd ontology/tools && pnpm build:sqlite && pnpm query concept "<term>"   # resolves names and aliases
pnpm query search "<term>"                                     # finds rules that mention it

• アイデアが既存の概念に関する事実なら、新しいノードではなく、そのファイルにルールを追加します。
• 既存のリソースの新しいフィールドや状態なら、そのファイルの fields または states に追加します。
• 新しいファイルを作成するのは、お客様やエージェントが単独で名前を付ける対象、または複数の概念にまたがるフローに限ります。

2. 種類を選ぶ

該当するもの	kind	例
API で独自の ID と CRUD を持つもの	resource	pod、template
独自の CRUD を持たないリソースの一部	component	worker、container-disk
読み取り専用の参照データ	catalog	gpu-type、data-center
リソースを使って行うこと	capability	pod-ssh-access
リソースが実行される Runpod のハードウェア	infrastructure	machine
請求またはクレジット	billing	pod-billing
上限またはクォータ	limit	api-rate-limit
Runpod の SDK または CLI	tool	flash
Runpod が参照するものの、所有はしていないもの	external	container-image
複数の概念にまたがって、何かがどのように順を追って進むか	process	pod-deployment

種類を示す親には is_a を設定します（cpu-pod is_a pod）。属する全体には part_of を設定します（worker part_of serverless-endpoint）。最上位の リソース、カタログ、請求のルート、ツール、制限は part_of: runpod-platform にします。

3. まず公開ソースを探す

公開ソースで裏付けられる内容だけを書きます。

ソース	場所	引用方法
REST v2 仕様	testdata/runpod-migrate/v2-openapi.json	source: rest-v2-spec、ref: Schema.field
公開ドキュメント	runpod/docs リポジトリ、または docs.runpod.io	source: public-docs、url: https://docs.runpod.io/<path>
このリポジトリ内のスキル	plugins/runpod/skills/	source: skill、path: plugins/runpod/skills/...
実行した読み取り専用リクエスト	ライブ API	source: live-probe、ref: にリクエスト、seen: に日付

主張を裏付ける公開ソースがない場合は、その内容を記載しません。内部文書、内部 ID、非公開リポジトリを引用しないでください。事前に確認せず、主張の検証のために課金対象のリソースを作成しないでください。

4. ファイルを作成する

類似ファイル（リソースなら pod.yaml、インフラストラクチャなら machine.yaml、プロセスなら pod-deployment.yaml）の形式を参考にして、次の項目を入力します。

1. id（ケバブケース。ファイル名は <id>.yaml）、name、kind、summary（顧客向けの1〜2文）、product、is_a、part_of、aliases。
2. surfaces：REST v2 のスキーマとパス、公開リファレンスに記載された GraphQL 名、MCP ツール、runpodctl コマンド、コンソールページ。
3. 概念に該当する場合は fields と states。REST v2 スキーマがある場合、すべてのフィールドはそのスキーマ、または作成／更新リクエストに存在する必要があります。
4. relations：concepts/README.md に記載された限定された種類から選びます。
5. rules：ルールごとに1つの事実を記述し、<concept-id>.<slug> 形式の ID を付けます。エージェントが実行できる内容を1〜3文で記述します。ルールが制約するフィールド、状態、またはアクションを applies_to で指定します。関連するルールを繰り返す代わりに、ほかの概念にあるルールを see: に指定します。

プロセスの場合は、順序どおりに steps を追加します。各ステップには id、title、description、関連する concepts、適用される rules を指定します。ステップからは、各概念にすでに存在するルールを参照します。プロセス全体に関係する事実のみをプロセス自体に記述します。たとえば、pod-deployment.stock-is-not-your-machine などです。

スタイルは、現在形を使い、コード識別子はバッククォートで囲み、「Runpod」のスペルを正しく記述します。「currently」や「not yet」のような語は使用しません。完全なリストは concepts/README.md の「Writing style」にあります。

# コメントは使用しないでください。pnpm format はデータからファイルを再生成し、コメントを削除してしまうため、コメントを含むファイルは拒否します。背景情報はエビデンスの note に記述してください。

5. 検証して確認する

cd ontology/tools
pnpm format              # canonical style; CI runs format:check
pnpm validate --strict   # must report 0 errors and 0 warnings
pnpm test
pnpm build:graph         # open ../build/graph.html

よくあるバリデーターエラー：

エラー	修正方法
... is not a concept	リレーション、is_a、part_of、フィールドの ref、またはステップで、存在しない ID が指定されています。
applies_to field:x, which ... does not declare	フィールドを追加するか、存在するフィールドを指定します。
mentions an internal ...	公開ソースに基づいてルールを書き直すか、削除します。
is time-bound	有効な内容を記述し、日付をエビデンスの seen に記載します。
YAML does not parse	[ ] または { } 内にある項目にコンマ、[]、{}、: 、# が含まれる場合は、その項目を引用符で囲みます。

グラフでノードを見つけ、リンクが適切か確認し、顧客の立場でパネルを一度読んでください。

6. ガイドをリンクする

すべての概念は、少なくとも1つのスキル、リファレンスドキュメント、またはゴールデンパスで扱う必要があります。そうでない場合、pnpm check:guides は失敗します。write-guide スキル（.claude/skills/write-guide/SKILL.md）に従って既存のドキュメントを拡張するか、新しいドキュメントを作成し、その概念をすでに扱っているドキュメントの内容がルールと引き続き一致することを確認してください。

7. コミットする

概念ファイルと、そこからリンクしているファイル、またはそのファイルへリンクしているファイルを、ノードの説明内容がわかる Conventional Commits 形式のメッセージでコミットします。例：docs(concepts): explain why a stopped pod may not restart。