How-tos -- INDEX
Live catalog of analysis-derived how-tos for the integrations-lifecycle skill.
Live-catalog rule (also stated in ../SKILL.md and
../recipes/INDEX.md): if an assistant is asked a concrete
question about the integrations pipeline that requires
non-trivial analysis (multiple file reads, running the
pipeline, cross-referencing schemas) AND the answer is not
already documented under one of the per-domain guides
(../pipeline.md, ../schema-reference.md, ../per-type-matrix.md,
../artifacts-and-banners.md, ../ibm-d.md,
../consistency.md, ../in-app-contract.md,
../gotchas.md) or the recipes (../recipes/), the
assistant MUST author a new how-tos/<slug>.md and add a
one-line entry to this INDEX BEFORE completing the task.
This is a durable rule. Skipping it means the next assistant repeats the same analysis from scratch -- a framework violation.
Catalog
| Topic | Slug | Notes |
|---|---|---|
Adding a new top-level integration_type (peer of collector, logs, exporter, etc.) |
adding-new-integration-type | 8-step recipe: schema, pipeline, templates, categories.yaml, map.yaml, source metadata, downstream repos. Covers what to clone from existing types, the hardcoded-vs-derived learn_rel_path distinction, and the integration_placeholder mechanism. |
Auditing metadata.yaml links to Learn |
auditing-metadata-learn-links | Commands and repair rules for finding absolute Learn URL drift, validating fragments, and checking source-relative metadata links. |
| Keeping Network Flows on the Learn "Monitor anything" page | monitor-anything-network-flows | Explains that src/collectors/COLLECTORS.md is generated by gen_doc_collector_page.py, why top-level flows must be treated as a section, and how to validate the generated Network Flows section. |
| Understanding collector taxonomy generation | taxonomy-yaml-to-taxonomy-json | General flow from collector metadata.yaml + taxonomy.yaml through validation to generated integrations/taxonomy.json, with references to the executable source of truth. |
Description authoring rules live in ../description-authoring.md
because they apply to all metadata authors, not only to one
analysis how-to.
How to add a how-to
- Create
how-tos/<slug>.mdwith:- A one-line summary at the top (the question being answered).
- The answer with file:line citations into this repo.
- A "How I figured this out" footer naming the files read and the commands run, so the next assistant can verify or extend.
- Add a row to the table above with topic, slug, and short notes.
- Commit alongside the work that prompted the analysis.
When NOT to add a how-to
- The question is already covered by an existing per-domain guide or recipe -- update that guide instead.
- The answer is a one-liner that doesn't require analysis (e.g. "where does X live?" -> just look it up; not how-to worthy).
- The answer is highly speculative or version-specific (e.g. about a feature that may change in the next release). In that case, note it in the conversation but don't bake into the durable catalog.