# Chart Skills Contract

**UNOFFICIAL/EXPERIMENTAL.** Schema and derivation rules for
[skills.csv](./skills.csv) and [skills.json](./skills.json), generated by
`scripts/generate-chart-skills.mjs`. Data and contract are generated from the
same constants, so they cannot drift.

## Purpose

Make "is there a skill for this chart?" answerable as data: per chart, which
[docs/skills/](../../docs/skills/README.md) playbook(s) apply and why. Advisory,
derived from the master matrix — not a proof.

## Columns (skills.csv)

| Column | Meaning |
| --- | --- |
| `chart` / `version` | Source chart and version. |
| `applicable_skills` | Slugs of the playbooks that apply, in catalog order. |
| `skill_count` | Number of applicable skills (0 = plain chart). |
| `top_skill` | The most specific applicable skill, or `none`. |
| `matched_signals` | The chart-fact tokens that triggered the mapping. |
| `skill_docs` | Playbook doc paths. |

`skills.json` adds, per applicable skill, its title, doc, and the `why`, plus
a `skills_catalog` block documenting every skill and its rule.

## Derivation rules

Facts are aggregated per chart from the master matrix (union of
`quirk_features` tokens across variants, max `hook_count`, and a live flag
from `outcome_level`/`catalog_tier`). A chart is **serious** if it is a named
hard chart or its `quirk_features` has both `crds` and `webhooks`.

| Skill | Playbook | Applies when |
| --- | --- | --- |
| `serious-chart-playbooks` | [Serious Chart Playbooks](../../docs/skills/serious-chart-playbooks.md) | named hard chart (kube-prometheus-stack, consul, cert-manager, external-secrets, loki) OR quirk_features has both crds and webhooks |
| `hook-and-secret-lifecycle` | [Hook And Secret Lifecycle](../../docs/skills/hook-and-secret-lifecycle.md) | hook_count > 0 OR quirk_features has hooks, generated-facts, or webhooks |
| `target-facts-and-lifecycle` | [Target Facts And Lifecycle](../../docs/skills/target-facts-and-lifecycle.md) | quirk_features has crds, webhooks, lookup, generated-facts, stateful-storage, or required |
| `large-app-evidence-funnel` | [Large App Evidence Funnel](../../docs/skills/large-app-evidence-funnel.md) | quirk_features has crds OR the chart is serious (proxy for many-Unit charts, pending a per-chart object count) |
| `live-parity` | [Live Parity](../../docs/skills/live-parity.md) | outcome_level shows local-live / live-parity / two-cluster, OR catalog_tier is catalog-supported |

## Named serious charts

- `external-secrets/external-secrets`
- `grafana/loki`
- `hashicorp/consul`
- `jetstack/cert-manager`
- `prometheus-community/kube-prometheus-stack`

## Determinism

A pure function of `data/master-catalog-matrix/matrix.csv`. No timestamps, no network, no cluster.
Regenerate with `npm run chart-skills`; verify byte-for-byte with
`npm run chart-skills:verify`.