Skip to content
Skills Library
Programming · Writing

write-guide

/write-guide

Write or change a skill, reference doc or golden path in this repo so it agrees with the concept graph and is linked to it. Use when adding or editing any SKILL.md, reference/*.md or golden path, and after adding or changing a concept so the docs that cover it are updated too. Pairs with the add-concept skill, which covers the concept files themselves.

Licence
Apache-2.0
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Write or change a skill, reference doc or golden path in this repo so it agrees with the concept graph and is linked to it. Use when adding or editing any SKILL.md, reference/*.md or golden path, and after adding or changing a concept so the docs that cover it are updated too. Pairs with the add-concept skill, which covers the concept files themselves.

Original author description

Write or change a skill, reference doc or golden path in this repo so it agrees with the concept graph and is linked to it. Use when adding or editing any SKILL.md, reference/*.md or golden path, and after adding or changing a concept so the docs that cover it are updated too. Pairs with the add-concept skill, which covers the concept files themselves.

How it works

  1. Writing or changing a guide
  2. After adding or changing a concept
  3. Style
  4. Check
Original SKILL.md headings · 87 lines, 633 words
SKILL.md preview
---
name: write-guide
description: Write or change a skill, reference doc or golden path in this repo so it agrees with the concept graph and is linked to it. Use when adding or editing any SKILL.md, reference/*.md or golden path, and after adding or changing a concept so the docs that cover it are updated too. Pairs with the add-concept skill, which covers the concept files themselves.
metadata:
  internal: true
---

# Write a guide against the concept graph

This repo has two kinds of content that must agree:

- **Concepts** (`plugins/runpod/skills/runpod-usage/concepts/*.yaml`) hold exact facts as
  rules, each citing a public source. They are the source of truth for *what is true*.
- **Guides** (every `SKILL.md`, `reference/*.md` and golden path) explain, teach and
  demonstrate. They are the source of truth for *how to do it*.

A guide states facts that the concept rules support, and links to the concepts it covers.
A concept is covered by at least one guide. `pnpm check:guides` enforces both links.

## Writing or changing a guide

1. **Find the concepts it touches** before writing (run these in `ontology/tools/`):

   ```bash
   pnpm build:sqlite
   pnpm query tree "<concept>"      # the concept, its children and the guides that cover them
   pnpm query search "<question>"   # the rules that answer a question
   pnpm query concept "<name>"      # every rule on one concept, with evidence
   ```

2. **Write from the rules.** Every factual claim (a limit, a default, a state, what an action
   does, what exists) must match a rule. Explain it in your own words and add the *how*: the
   commands, order, pitfalls and verification.
   - If the guide needs a fact that no rule has, **add the rule first** with the
     `add-concept` skill, citing the spec, the public docs or a live probe. Then write the
     guide.
   - If a rule is wrong or out of date, fix the rule (and its evidence) in the same change.
   - Never let a guide and a rule say different things. If you find a disagreement, the
     public source decides which one changes.

3. **Declare the links.**

   | Guide | Where | Example |
   |---|---|---|
   | `SKILL.md` | `metadata.concepts` in the frontmatter | `concepts: [pod, network-volume]` |
   | Reference doc | a `concepts:` line in frontmatter at the top | `---`<br>`concepts: [runpod-secret]`<br>`---` |
   | Golden path | `lanes`, `mcp` and `concepts` in frontmatter | see `plugins/runpod/skills/runpod/golden-paths/README.md` |

   List the concepts the guide actually explains or uses, not every word it mentions.
   `pnpm build:bundle --suggest` lists the concepts each golden path names, as candidates.
   A reference doc that a rule already cites as evidence is linked automatically, but list
   its concepts anyway when it covers more than the citing rules.

4. **Point to the rules** when a doc is the main explanation of a concept. End it with a short
   "Exact rules" section with a Markdown link to each concept file (from a reference doc the
   target is `../concepts/<id>.yaml`).

5. **Route it.** A new reference doc gets a row in its skill's `SKILL.md` table. A new golden
   path gets rows in the router's table and `golden-paths/README.md`.

## After adding or changing a concept

1. `pnpm check:guides` fails if the new concept has no guide. Extend an existing doc or write
   a new one, following the steps above.
2. Find the guides that already cover it and check they still agree with the rules:

   ```bash
   pnpm query tree "<concept>"                    # guides linked to it
   grep -rln "<name or alias>" ../../plugins/     # guides that mention it without a link
   ```

3. When a rule cites a skill file as evidence and you change that file, re-read the rule:
   `grep -rn "<path>" ../../plugins/runpod/skills/runpod-usage/concepts/`.

## Style

Follow `plugins/runpod/skills/runpod-usage/concepts/README.md` → "Writing style" and the
repo conventions in `AGENTS.md`: plain present tense, "Runpod", code identifiers in
backticks, no "currently" or "not yet", and positive claims over claims that something is
missing (a missing capability needs the spec or docs as evidence, and CLI absence claims are
checked by `hooks/check_cli_absence_claims.py`).

## Check

```bash
cd ontology/tools
pnpm format && pnpm validate --strict && pnpm check:guides && pnpm test
cd ../.. && python3 hooks/check_links.py && python3 hooks/check_runpod_branding.py
```

`check:guides` must report no errors, and the build line "concepts with a guide" must stay at
every concept.

Versions

RepositoryScoreLicence
This page · runpod/runpod-plugins-official100Apache-2.0
vercel/next.js100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version d0de5dda4913 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100add-concept
    Add or change a node in the Runpod concept graph (plugins/runpod/skills/runpod-usage/concepts/*.yaml), including process nodes that explain how something works step by step. Use when asked to add a concept, add a rule to one, document how a Runpod flow works, or fix a node.…
  • 100write-docs
    Use when writing or editing documentation pages (concept pages, how-to guides, API reference prose, tutorials) under docs/. Provides the writing style, voice, and structural rules for Agenta docs. Apply this skill before drafting any new docs page, and include it in the brief…
  • 90concept-model
    Guide new development and maintenance with concise concept principles. Use for state and behavior ownership, concept boundaries, or cross-concept collaboration; complements ub-mode.
  • 100scan
    [Documentation] Use when a workflow step or the user asks for one project-reference doc rebuild via --target=<key>, preserving verified rules. All selected reference docs: scan-all.
  • 100scan
    [Documentation] Use when a workflow step or the user asks for one project-reference doc rebuild via --target=<key>, preserving verified rules. All selected reference docs: scan-all.
  • 100ref-model
    Builds Phase 2 golden C reference model with bitexact conformance and bandwidth estimation. Use for 'build reference model', 'C ref model', 'golden model'.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.