# Telemetry Contracts

> Enforce telemetry contract stability (event naming, JSONL envelopes, /api/health + /api/status shape). Use when investigating telemetry drift, adding new telemetry fields, or updating z-server ingestion/UI.

- Skill: `majiayu000/telemetry-contracts` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/telemetry-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/telemetry-contracts/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/telemetry-contracts

---


# Telemetry Contracts

## Scope

This Skill helps keep telemetry reliable over time by:

- identifying the contract surfaces (events + endpoints)
- updating code + tests together
- validating that drift risks are addressed

Out of scope:

- designing brand-new telemetry systems (that’s a separate design task)

## Inputs

- Which server/module emits telemetry (file path(s) if known)
- What changed (new fields, renamed events, endpoint shape change)
- Which consumer(s) are impacted (e.g. z-server, UI dashboards, tests)

## Procedure

1. Locate current contract docs + recent telemetry work.
   - Start from the most recent telemetry session docs under `docs/sessions/`.
2. Identify the contract surfaces that must remain stable:
   - telemetry JSONL envelope shape
   - event names + required fields
   - `/api/health` and `/api/status` payload shape
3. Update emitter and consumer in lockstep.
4. Add/adjust the smallest test(s) that enforce the contract.
5. Record the rationale (why the shape changed, migration plan if needed).

## Validation

- Run the most targeted test suite(s) that cover telemetry shape.
- If the change affects diagrams/docs, update the relevant session diagrams.

## Escalation / Research request

Ask for dedicated research if:

- a contract change affects multiple servers and you need a migration strategy
- you need a formal schema/versioning plan

## References

- Telemetry explainer session: `docs/sessions/2025-12-13-telemetry-setup-explainer/`
- AGI workflows: `docs/agi/WORKFLOWS.md`