integrations-lifecycle
The pipeline that turns source metadata into the integration pages, the umbrella pages, and the in-app catalog. This
skill owns the mechanics and the delivery rules; what a collector metadata.yaml field should say is
.agents/skills/collectors-metadata-yaml/, and config_schema.json is
.agents/skills/collectors-go-design/config-schema.md.
Apply AGENTS.md#skill-selection. For review, select the affected pipeline or artifact contract below and inspect
source plus existing validation evidence. Loading recipes does not require regeneration, dependency installation,
commits or publication. Authorized validation uses current inputs and preserves existing outputs through isolation.
Shared delivery facts:
metadata.yaml is the input. Hand-authored for most integrations; generated for ibm.d modules (from contexts.yaml,
config.go, module.yaml) and for the NPM catalog (from SNMP profiles by integrations/gen_npm_catalog.py). Edit
the authoritative source, never a generated file.
- Every
<dir>/integrations/<slug>.md, every README that is a symlink or whose <!--startmeta block carries a
message: "DO NOT EDIT..." line (a <!--startmeta block alone is not the marker; hand-authored Learn pages have one
too), and the umbrella pages src/collectors/COLLECTORS.md, SECRETS.md, SERVICE-DISCOVERY.md (no banner) are
generated. Do not edit them.
- Source PRs carry sources; generated documentation arrives through the post-merge
integrations-regen PR. Validate
with gen_integrations.py and the tests during authorized changes; preview pages in isolation using
how-tos/preview-collector-page.md (selected collectors or its non-collector route). Preserve existing generated-file edits and keep them out of the source commit.
The one place this boundary is written out, with its ibm.d runtime-output exception, is consistency.md.
- The collector taxonomy (
taxonomy.yaml, gen_taxonomy.py) is a dormant early implementation kept for later work;
nothing runs it. Do not author, extend, or seed taxonomy content (consistency.md, "The dormant collector taxonomy").
You edit metadata or a collector and need to validate and deliver
| Read |
For |
consistency.md |
which artifacts move together, the delivery boundary, what CI enforces, the review checklist, the dormant taxonomy |
integrations/README.md |
dependencies and the command list for a local run |
how-tos/preview-collector-page.md |
selected collector prose; its non-collector route covers flows and other types in an isolated source copy |
description-authoring.md |
the catalog sentence and the generated page meta description (the two cross-type description contracts) |
recipes/add-go-collector.md, recipes/update-collector.md |
step-by-step for a new or changed go.d collector |
ibm-d.md |
the ibm.d generation chain |
how-tos/INDEX.md |
retiring a collector, tracing a missing published section, auditing Learn links, Prometheus profiles and the catalog |
You change the generators, schemas, templates, or CI
| Read |
For |
pipeline.md |
stages, sources per integration type, validation and rendering, outputs and banners, page locations and learn_rel_path, umbrella pages, both workflows |
schema-reference.md |
what each schema validates and the behavior the schema file does not show |
gotchas.md |
dead code, silent behaviors, validation traps, the MDX incident |
in-app-contract.md |
how cloud-frontend consumes integrations.js and what it treats as a contract |
how-tos/INDEX.md |
adding an integration type, the NPM catalog generator |
Citations in this skill name files and symbols, never line numbers; open the file and search for the symbol.
Live how-to rule
Capture timing and authorization follow AGENTS.md#knowledge-capture. Pipeline recipes live in how-tos/ and are
listed in ./how-tos/INDEX.md; prefer updating an existing guide when it already covers most of the question.
Path discipline
.agents/sensitive-data-discipline.md applies: repository files repo-relative, sibling Netdata-org repositories as
${NETDATA_REPOS_DIR}/<repo>/..., no workstation paths.
Related skills
collectors-authoring: read first when authoring a brand-new collector; this skill covers the integration side.
collectors-metadata-yaml: the words on the page, field by field.
collectors-go-design/config-schema.md: the DynCfg form.
docs-learn-site-structure: how the generated pages reach learn.netdata.cloud (docs/.map/map.yaml, ingest,
redirects).
collectors-prometheus-profiles: the profile side of the Prometheus catalog.
1---2name: integrations-lifecycle-23description: Change or review the Netdata integrations pipeline, collector artifact consistency, metadata validation, generated docs/catalogs and source-versus-runtime delivery. Covers ibm.d and NPM producers, schemas, generators and dormant taxonomy. Metadata field prose uses collectors-metadata-yaml.4metadata:5 source: https://skillmd.com/skills/netdata/integrations-lifecycle-26---78# integrations-lifecycle910The pipeline that turns source metadata into the integration pages, the umbrella pages, and the in-app catalog. This11skill owns the mechanics and the delivery rules; what a collector `metadata.yaml` field should say is12`.agents/skills/collectors-metadata-yaml/`, and `config_schema.json` is13`.agents/skills/collectors-go-design/config-schema.md`.1415Apply `AGENTS.md#skill-selection`. For review, select the affected pipeline or artifact contract below and inspect16source plus existing validation evidence. Loading recipes does not require regeneration, dependency installation,17commits or publication. Authorized validation uses current inputs and preserves existing outputs through isolation.1819Shared delivery facts:2021- `metadata.yaml` is the input. Hand-authored for most integrations; generated for ibm.d modules (from `contexts.yaml`,22 `config.go`, `module.yaml`) and for the NPM catalog (from SNMP profiles by `integrations/gen_npm_catalog.py`). Edit23 the authoritative source, never a generated file.24- Every `<dir>/integrations/<slug>.md`, every README that is a symlink or whose `<!--startmeta` block carries a25 `message: "DO NOT EDIT..."` line (a `<!--startmeta` block alone is not the marker; hand-authored Learn pages have one26 too), and the umbrella pages `src/collectors/COLLECTORS.md`, `SECRETS.md`, `SERVICE-DISCOVERY.md` (no banner) are27 generated. Do not edit them.28- Source PRs carry sources; generated documentation arrives through the post-merge `integrations-regen` PR. Validate29 with `gen_integrations.py` and the tests during authorized changes; preview pages in isolation using30 `how-tos/preview-collector-page.md` (selected collectors or its non-collector route). Preserve existing generated-file edits and keep them out of the source commit.31 The one place this boundary is written out, with its ibm.d runtime-output exception, is `consistency.md`.32- The collector taxonomy (`taxonomy.yaml`, `gen_taxonomy.py`) is a dormant early implementation kept for later work;33 nothing runs it. Do not author, extend, or seed taxonomy content (`consistency.md`, "The dormant collector taxonomy").3435## You edit metadata or a collector and need to validate and deliver3637| Read | For |38|---|---|39| `consistency.md` | which artifacts move together, the delivery boundary, what CI enforces, the review checklist, the dormant taxonomy |40| `integrations/README.md` | dependencies and the command list for a local run |41| `how-tos/preview-collector-page.md` | selected collector prose; its non-collector route covers flows and other types in an isolated source copy |42| `description-authoring.md` | the catalog sentence and the generated page meta description (the two cross-type description contracts) |43| `recipes/add-go-collector.md`, `recipes/update-collector.md` | step-by-step for a new or changed go.d collector |44| `ibm-d.md` | the ibm.d generation chain |45| `how-tos/INDEX.md` | retiring a collector, tracing a missing published section, auditing Learn links, Prometheus profiles and the catalog |4647## You change the generators, schemas, templates, or CI4849| Read | For |50|---|---|51| `pipeline.md` | stages, sources per integration type, validation and rendering, outputs and banners, page locations and `learn_rel_path`, umbrella pages, both workflows |52| `schema-reference.md` | what each schema validates and the behavior the schema file does not show |53| `gotchas.md` | dead code, silent behaviors, validation traps, the MDX incident |54| `in-app-contract.md` | how cloud-frontend consumes `integrations.js` and what it treats as a contract |55| `how-tos/INDEX.md` | adding an integration type, the NPM catalog generator |5657Citations in this skill name files and symbols, never line numbers; open the file and search for the symbol.5859## Live how-to rule6061Capture timing and authorization follow `AGENTS.md#knowledge-capture`. Pipeline recipes live in `how-tos/` and are62listed in `./how-tos/INDEX.md`; prefer updating an existing guide when it already covers most of the question.6364## Path discipline6566`.agents/sensitive-data-discipline.md` applies: repository files repo-relative, sibling Netdata-org repositories as67`${NETDATA_REPOS_DIR}/<repo>/...`, no workstation paths.6869## Related skills7071- `collectors-authoring`: read first when authoring a brand-new collector; this skill covers the integration side.72- `collectors-metadata-yaml`: the words on the page, field by field.73- `collectors-go-design/config-schema.md`: the DynCfg form.74- `docs-learn-site-structure`: how the generated pages reach `learn.netdata.cloud` (`docs/.map/map.yaml`, ingest,75 redirects).76- `collectors-prometheus-profiles`: the profile side of the Prometheus catalog.