Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.
Add a concept to the graph
Each node is one YAML file in plugins/runpod/skills/runpod-usage/concepts/ (called concepts/ below). The format, kinds, relation types and writing style are defined in concepts/README.md. Read it before writing; this skill is the procedure, not the format.
Every file is public-facing. Everything in it must be safe to show a customer and backed by a public source. The validator enforces this.
1. Check it doesn't already exist
Search ids, names and aliases before creating anything:
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- If the idea is a fact about an existing concept, add a rule to that file instead of a new node.
- If it is a new field or state of an existing resource, add it to that file's
fieldsorstates. - Create a new file only for a thing a customer or agent names on its own, or for a flow that spans concepts.
2. Pick the kind
| If it is… | kind | Example |
|---|---|---|
| Something with its own id and CRUD in the API | resource | pod, template |
| Part of a resource with no CRUD of its own | component | worker, container-disk |
| Read-only reference data | catalog | gpu-type, data-center |
| Something you do with a resource | capability | pod-ssh-access |
| Runpod hardware a resource runs on | infrastructure | machine |
| Charges or credit | billing | pod-billing |
| A cap or quota | limit | api-rate-limit |
| A Runpod SDK or CLI | tool | flash |
| Something Runpod references but doesn't own | external | container-image |
| How something works, in order, across concepts | process | pod-deployment |
Set is_a for a kind-of parent (cpu-pod isa `pod`). Set `partof for the whole it belongs to (worker part_of serverless-endpoint). Top-level resources, catalogs, billing roots, tools and limits sit part_of: runpod-platform`.
3. Find public sources first
Write only what a public source supports:
| Source | Where | Cite as |
|---|---|---|
| REST v2 spec | testdata/runpod-migrate/v2-openapi.json | source: rest-v2-spec, ref: Schema.field |
| Public docs | the runpod/docs repo, or docs.runpod.io | source: public-docs, url: https://docs.runpod.io/<path> |
| Skills in this repo | plugins/runpod/skills/ | source: skill, path: plugins/runpod/skills/... |
| A read-only request you ran | the live API | source: live-probe, ref: the request, seen: the date |
If no public source supports a claim, leave it out. Don't cite internal documents, internal ids or private repositories. Don't create billable resources to verify a claim without asking first.
4. Write the file
Copy the shape of a similar file (pod.yaml for a resource, machine.yaml for infrastructure, pod-deployment.yaml for a process) and fill in:
id(kebab-case; the file is<id>.yaml),name,kind,summary(one or two customer-facing sentences),product,is_a,part_of,aliases.surfaces: the REST v2 schema and paths, GraphQL names from the public reference, MCP tools,runpodctlcommands, console page.fieldsandstatesif the concept has them. With a REST v2 schema, every field must exist on that schema or its create/update request.relations, from the closed set inconcepts/README.md.rules: one fact per rule, with an id of<concept-id>.<slug>. Write one to three sentences an agent can act on. Pointapplies_toat the fields, states or actions the rule constrains. Put related rules on other concepts insee:instead of restating them.
For a process, add steps in order. Each step has an id, title, description, the concepts it involves and the rules that govern it. Steps link to rules that already exist on the concepts. Put only the facts that belong to the flow as a whole on the process itself, such as pod-deployment.stock-is-not-your-machine.
Style: plain present tense, code identifiers in backticks, "Runpod" spelled correctly, and no words like "currently" or "not yet". The full list is in concepts/README.md under "Writing style".
Don't use # comments: pnpm format rewrites the file from its data and refuses a file with a comment, since it would drop it. Put the context in a note on the evidence instead.
5. Validate and look at it
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.htmlCommon validator errors:
| Error | Fix |
|---|---|
... is not a concept | A relation, is_a, part_of, field ref or step names a missing id. |
applies_to field:x, which ... does not declare | Add the field, or point at one that exists. |
mentions an internal ... | Restate the rule from a public source, or delete it. |
is time-bound | Say what holds, and put the date in evidence as seen. |
YAML does not parse | Quote any item inside [ ] or { } that contains a comma, [], {}, : or #. |
In the graph, find the node, check that its links make sense, and read its panel once as a customer would.
6. Link a guide
Every concept must be covered by at least one skill, reference doc or golden path; pnpm check:guides fails otherwise. Follow the write-guide skill (.claude/skills/write-guide/SKILL.md) to extend an existing doc or write a new one, and to check that the docs already covering the concept still agree with its rules.
7. Commit
Commit the concept file, plus any other files you linked from or to, with a Conventional Commits message that says what the node explains, for example docs(concepts): explain why a stopped pod may not restart.
