Collectors Metadata YAML

Collector metadata.yaml: The Page The User Reads

metadata.yaml is the source of the integration page on Learn and of the catalog row that leads to it. Users open that page to decide whether to run the collector, what they will get, what it needs, and what it costs. Every field in it is product copy for an operator, not developer documentation. This skill owns what each field says and how it reads.

Use By Task

• Explain a field: read its family below and the shared reading/Markdown rules.
• Review metadata or page content: apply the relevant field contracts and checklist to the assigned scope. A full page review uses all five families. Loading this skill does not authorize edits or generation in the checkout.
• Edit content: verify claims against current source, then use the lifecycle validation and isolated preview routes. ibm.d changes must reach the generated metadata through its producer; editing module.yaml alone does not refresh it.
• Review a collector through another lens: load the affected family when wording, permissions, defaults, cost, or operator behavior matters to that lens; this does not expand the assigned review scope.

Ownership

• This skill: the content of every collector metadata.yaml field: what it answers, in what order, in what shape, for whom. Rules are cross-plugin. ibm.d metadata is generated by docgen and never edited: module.yaml holds the identity, overview description, and explicit page page_description; contexts.yaml holds the metric rows. Other fields (method, permissions, default behavior, option rows, prerequisites, examples, troubleshooting) use docgen's metadata template (src/go/plugin/ibm.d/docgen/main.go, see integrations-lifecycle/ibm-d.md), so applying these rules there means changing the template. Keywords derive from the module name; page_description becomes meta.monitored_instance.description. config.go feeds the schema and README, not the options table.
• .agents/skills/integrations-lifecycle/: mechanics. JSON schemas, generators, validation commands, artifacts and banners, the ibm.d generation chain, and the cross-type page meta-description derivation contract (description-authoring.md).
• .agents/skills/collectors-go-design/config-schema.md: the DynCfg form. Option wording shared between the form and the options table has one owner there (sections 7 and 8); this skill points to it.
• .agents/skills/collectors-go-design/operator-surface.md: which options exist and what an operator decides. Decided before this skill applies.

How The Page Is Rendered

Facts every rule below relies on (integrations/templates/overview/collector.md and siblings):

• The template owns the heading hierarchy (h1 title; h2 Overview, Setup, Troubleshooting, Alerts, Metrics, and Live Data when the collector has Functions; h3 to h6 inside them, down to one h5 per option depth block and one h6 per example). Field text is inserted under those headings as-is.
• Field text is Markdown rendered by Docusaurus on Learn. Paragraphs, lists, tables, inline code, fenced code, links, and ::: admonitions (note, tip, caution) pass through the generator untouched.
• Some empty fields are not empty on the page. auto_detection, limits, and performance_impact render a template placeholder sentence that asserts something about the collector (see overview.md). An empty field is a claim.
• The first sentence of metrics_description supplies the catalog row. Page meta descriptions have separate override-first resolution and length rules in integrations-lifecycle/description-authoring.md.
• Generated pages under integrations/ and the README.md symlink are outputs. Fix the source; never edit them.

The Reading Model

• The reader is an operator scanning a page, deciding in this order: what is this, what do I get, what do I need, what does it cost, how do I set it up, what went wrong. Fields are ordered that way by the template; write each field for the question it sits under.
• Readers stop when they have enough. The first paragraph of every field MUST stand alone; detail follows in decreasing importance.
• metrics_description and method_description carry the page. They sit above the fold, most visitors read no further, and the first sentence of metrics_description becomes the catalog row that decides whether anyone opens the page at all. When writing or reviewing time is short, spend it on those two.
• Readers skip walls of text ("I ain't reading all that"). Long content is fine when it is structured: one idea per paragraph, lists for enumerations, tables for items that share attributes, an admonition for what must not be missed. Length is a symptom to check, not the rule; an unstructured 120-word paragraph fails, a 400-word field made of a table and three short paragraphs may pass.
• Paragraph breaks are not structure, and no shape test decides this. A field can sit under every length bound, break cleanly into four paragraphs, and still be a wall, because the reader must read all of it to find the part that concerns them; redfish shipped exactly that (overview.md section 3). Conversely s3check's method_description is three plain paragraphs, the longest 114 words, and passes, because every sentence in it is a consequence the operator can act on. Judge the field by the question it answers and by what the reader can do with each sentence, never by its silhouette.
• Operator voice. The page describes what the collector does as the operator sees it: connections, requests, commands, files, permissions, what it creates and deletes, what it never touches. Unexplained implementation mechanics that do not affect operation MUST NOT appear. Preserve operator-visible terms and exact public names (for example journal storage or snapshot APIs); define unfamiliar terms at first use.

Routing By Field Family