Agent-Skills.md

Agent Skills: Telemetry & Cost Reporting

Enforce session-cost telemetry and execution-metadata reporting. Use when explicitly invoking get_session_cost, reporting token/cost usage, applying telemetry or cost guidance during a workflow handoff, or writing artifacts/session-cost.md at a workflow terminal state.

UncategorizedID: hoangnguyen0403/agent-skills-standard/common-telemetry

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: MIT
567164

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/.codex/skills/common/common-telemetry

Skill Files

Browse the full folder contents for common-telemetry.

Download Skill

Loading file tree…

.codex/skills/common/common-telemetry/SKILL.md

Skill Metadata

Name
common-telemetry
Description
Enforce session-cost telemetry and execution-metadata reporting. Use when explicitly invoking get_session_cost, reporting token/cost usage, applying telemetry or cost guidance during a workflow handoff, or writing artifacts/session-cost.md at a workflow terminal state.

Telemetry & Cost Reporting

Priority: P2 (MEDIUM)

1. Finalizing a Workflow

As your final step in any SDLC workflow (or when a user explicitly requests session cost):

  1. Call the get_session_cost tool provided by the agent-skills-standard MCP server.
  2. Pass workflow, model, token counts, cache/reasoning usage, and per-1M token rates when the host runtime exposes them. Set slug (feature/workspace name) and outcome (terminal feature_status) when this call finalizes a workflow, so the telemetry log can attribute cost per feature.
  3. Never set costSource: "host" yourself — that value is reserved for the runtime's own telemetry adapter (buildSessionCostRequest). If you type numbers by hand, omit costSource so the tool reports them as agent-estimate, never host.
  4. If token counts are unavailable, report MCP-observed telemetry and let get_session_cost mark cost provenance as unavailable — never fabricate a number or a $0.00 total.
  5. Append a Markdown table containing the usage metrics to artifacts/session-cost.md.

When asked which artifact to use, always name both artifacts/session-cost.md and get_session_cost; if the host does not expose the helper, say so explicitly while retaining the artifact requirement.

2. Accounting Boundaries & Lineage Semantics

  • Missing ≠ Zero: When metric fields or token counts are missing from runtime events, treat them as unknown or unavailable. Never coerce missing values to 0 or calculate $0.00 totals from partial data.
  • Partial Lineage & Incomplete Rates: If pricing rates, cache rates, reasoning rates, or token lineage across subagents are incomplete, mark total cost as unknown or partial. Do not report exact cost figures without complete rate coverage.
  • Subagent & Worker Cost Scope: Shared parent orchestration costs and worker-only slices represent partial task scope. Never claim subagent-only costs as full-task totals or assert net savings without measured baselines.
  • Discovery Lifecycle Distinctness: Do not conflate resource state transitions. Catalog discovery (skills listed/indexed) ≠ body fetched (skill markdown loaded) ≠ delivered to agent context ≠ actively used/applied in generation. Persisted telemetry must not assert usage when only discovery or delivery occurred.
  • Efficacy & Savings Claims: Never claim model efficacy uplift or token savings without qualified, independently reproducible measurement evidence against an authoritative baseline.

3. Host Runtime Contract

  • This skill defines the telemetry contract; it does not collect provider billing data by itself.
  • The host runtime or orchestrator must trigger the final telemetry call when the workflow reaches a terminal state such as completed, failed, or blocked.
  • The host may use a reusable helper such as mcp/src/services/WorkflowTelemetry.ts to:
    • decide when telemetry should fire
    • build the get_session_cost payload
    • pass prompt, cache, reasoning, pricing, and other runtime cost fields when available

4. Telemetry Format

Ensure the artifacts/session-cost.md or the output template ## Cost Report follows this structure, copying the get_session_cost output verbatim rather than re-deriving values:

| Metric | Value | | ------------------------ | ------------------------------------------------------- | | Tool Calls | [from get_session_cost] | | Skills Loaded | [from get_session_cost] | | Workflows Loaded | [from get_session_cost] | | Prompt Tokens | [from get_session_cost, or "unavailable" if not exposed] | | Cached Prompt Tokens | [from get_session_cost, or "unavailable" if not exposed] | | Completion Tokens | [from get_session_cost, or "unavailable" if not exposed] | | Reasoning Tokens | [from get_session_cost, or "unavailable" if not exposed] | | Other Runtime Cost | [from get_session_cost, or "unavailable" if not exposed] | | Cost Provenance | host | agent-estimate | unavailable | | Estimated Cost | [from get_session_cost, or "unavailable" — never $0.00] |

Anti-Patterns

  • No skipping the telemetry step: Always include the Cost Report at the end of the execution if mandated by the workflow.

  • No fabricated numbers: Never invent a $0.00 or any other placeholder cost when get_session_cost reports unavailable; render the provenance value as-is.

  • No zero-coercion of missing metrics: Missing token or rate fields must stay unknown or unavailable; never coerce to 0.

  • No conflating catalog discovery with usage: Listing a skill or fetching its markdown does not imply it was used in model generation.

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

  • Call get_session_cost when the host exposes it, then append the Markdown table to artifacts/session-cost.md.

  • Cost Provenance: host, agent-estimate, unavailable

  • Telemetry & Cost Reporting