Skills#
.claude/skills/ holds authoring conventions that are consumed by both contributors and AI agents.
They exist so a convention lives in one place rather than being re-explained per reviewer, and so an agent picks up the same opinions a reviewer would apply.
Each skill is a SKILL.md with front matter naming when it applies, plus optional references/, assets/, and scripts/ beside it.
| Skill | Applies when |
|---|---|
yaml-development | editing any .yaml / .kyaml — formatting conventions and the deliberate yamllint relaxations |
chart-development | changing anything under charts/* — templates, values.yaml, subchart wrapping, profiles, helm-unittest |
platform-development | changing terraform/, test/e2e/, or the CI gating them — and chart changes with consequences for either |
deployment-operations | standing up the stack against a real or local cluster, or diagnosing an unhealthy one |
dashboards-as-code | authoring Grafana dashboards in packages/grafana-dashboards |
pipelines-as-code | authoring Alloy pipelines in packages/alloy-pipelines |
Related skills outside this repo#
The agent-skills repository carries org-wide skills, including one for materialize-terraform-self-managed — the repo the per-cloud monitoring wrappers live in.
The two are not synced, and deliberately so for now: this repo’s platform-development covers the common module and the chart it installs, while that one covers the deployment repo as a whole. The seam worth watching is the wrapper contract — the object_storage shape, the ServiceAccount names its trust policies must match, and the fact that a wrapper pins the module by released tag. If that contract changes here, the downstream skill is the thing most likely to go quietly stale.
Skills are thin on purpose#
A skill routes; it does not duplicate. Substantive content belongs in these docs — operators hit the same problems contributors do, and a troubleshooting entry only readable inside a skill file helps nobody with a broken cluster.
The two newest follow that split deliberately:
deployment-operationsis mostly pointers into o11y Troubleshooting, Uninstalling, and Production Best Practices. What it keeps for itself is the habits — name the cluster explicitly, assert on recent data rather than any data, treat a greenhelm upgradeas no evidence a change took effect.platform-developmentkeeps the reasoning that has no natural operator-facing home: why the module fans values out at all (Helm cannot template subchart values from a parent), whyterraform validateproves almost nothing, and the handful of HCL andyamlencode/yamldecodebehaviours that produce valid-but-wrong config.
When a skill starts accumulating prose, that is the signal to move it into a doc and leave a link.