telemetry-contracts
强制遥测合约稳定性(事件命名、JSONL信封、/api/health + /api/status形状)。在调查遥测漂移、添加新的遥测字段或更新z-server摄取/UI时使用。
📖 中文导读:强制遥测合约稳定性(事件命名、JSONL信封、/api/health + /api/status形状)。在调查遥测漂移、添加新的遥测字段或更新z-server摄取/UI时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: telemetry-contracts description: 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.
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
- Locate current contract docs + recent telemetry work.
- Start from the most recent telemetry session docs under
docs/sessions/.
- Start from the most recent telemetry session docs under
- Identify the contract surfaces that must remain stable:
- telemetry JSONL envelope shape
- event names + required fields
/api/healthand/api/statuspayload shape
- Update emitter and consumer in lockstep.
- Add/adjust the smallest test(s) that enforce the contract.
- 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