using-system
UserCLI toolbox for Observability-Driven Development (ODD): coding agents observe local runs on an OpenTelemetry/Grafana stack - or remote ones on any OpenTelemetry backend - and feed the next spec-driven improvement loop.
Categories
Indexed Skills (19)
check-backend-configuration
Display, verify, and guide the observability CLI configuration for the configured stack backend before an observation or verify run. Use before dispatching an observe/verify mission, when the configured stack must be confirmed, when the backend CLI's connection must be proven, or when the user needs guidance to set their CLI up. Stack-agnostic - everything about a given stack comes from its observability-cli-guides reference. Never authenticates on the user's behalf - it verifies, displays, and guides.
create-observe-run-report
Persist an observation report into the observed repository at .odd/observe-run-reports/ with a structured frontmatter, and recall previous reports for the same service - the file contract that turns single observation runs into the ODD loop's memory. Use when storing the report an observation run produced, or when loading past reports to establish a baseline before a new run.
create-otel-instrumentation-report
Persist an OpenTelemetry instrumentation investigation report into the investigated repository at .odd/otel-instrumentation-reports/ with a structured frontmatter, commit it, and recall previous investigations of the same project - the file contract that keeps instrumentation expertise feeding later SDD waves. Use when storing the report an instrumentation investigation produced, or when loading past investigations before a new one.
get-status
Render the state of the ODD loop from the repository's committed .odd/ history and git alone - one screen by default (the loop state per lineage with its burn-down and next action), the full tables on request (per-service loop state, findings ledger, trends, open telemetry gaps) - read-only, no backend queries, no report written. Use when answering where the loop is, when /odd-status runs, or when a status must be computed offline from the clone.
run-scenario
Drive a reproducible request scenario against a locally running service - ad-hoc requests, or a stored k6 benchmark from .odd/benchmarks/ - and record it verbatim, so the telemetry it produces can be compared with a later run. Use when traffic must be generated before observing a service, when a stored k6 benchmark must be run, when an observation report needs a replayable scenario, or when verifying after a fix that the same scenario now measures better.
setup-local-stack
Configure gcx against the local oddyssey Grafana stack and query its four signals (metrics, traces, logs, profiles) without touching the user's own gcx contexts. Owns the global configuration's "local" stack value. Use when the configured stack is "local", when querying the local stack (Grafana host port from the global configuration, default 3000), when configuring gcx locally, when a command needs the Tempo, Prometheus, Loki, or Pyroscope datasource UID. gcx is the mandatory query CLI for the stack - install it if missing (brew install gcx, or the official install script from github.com/grafana/gcx).
show-observe-run-report
Render a short synthesis of a persisted observation report for the human closing the mission - verdict-first headline, the stored path, a compact run block, the findings that matter, and the recommended next action - never a replacement for the report itself. Use when an /odd-observe or /odd-verify mission ends and the final answer must synthesize the stored report instead of dumping it raw.
observability-cli-guides
The package's knowledge of every observability stack it supports, one reference file per stack - the terminal query surface (how to authenticate and query metrics, traces, logs, and profiles from the CLI), how the stack's configuration is displayed and proven, and what its stack_config persists - plus the list of built-in stacks. Use when observing a run, local or remote, and when backend-configuration's Check or Switch need anything about a stack - Grafana (gcx), Datadog (Pup CLI), Dynatrace (dtctl and DQL), Azure Monitor (az), AWS CloudWatch and X-Ray (aws), and the local stack.
k6-guides
Curated map of the official k6 load-testing docs - installation, running a script, scripting (checks/thresholds/scenarios), test types, protocols, and which questions a benchmark's inputs require before it can be authored. Use when authoring or reasoning about a k6 benchmark - pick the topic, open its reference file, and follow the linked official docs. Read by /odd-instrument-bench (which questions to ask), k6-benchmark-expert (authoring and validating), a stored benchmark's replay (running one), and the /odd-instrument-bench, /odd-observe, and /odd-verify preflights (ensuring k6 is present).
backend-configuration
Own the configured observability backend, in two sections invoked by name. Check: display the configured stack and the instance the runs will hit, prove the CLI connected, guide the user when it is not, and hand the preflight over to the mission. Switch: verify the target backend's CLI is installed (offer a guided install when missing), persist the switch via odd_config_set, persist the per-stack stack_config values the missions will need, then run Check for the proof. Stack-agnostic - the stack list and everything about a given stack come from the observability-cli-guides skill. Use before dispatching an observe, verify or bench mission, when the configured stack must be confirmed or the CLI's connection proven, when the user needs guidance to set their CLI up, and when the user asks to change the configured backend or to persist targeting values. Never installs silently, never authenticates on the user's behalf, never stores or echoes a secret.
odd-memory
The .odd/ memory - its contract and one reference per kind. The contract states what every kind shares (where the memory lives, the frontmatter and the whole body, append-only reports versus living-source benchmarks, recall by frontmatter then by section, the no-secrets rule, the work branch and the lone commit, the reply that carries a synthesis and never the artifact); each reference says how to persist, recall and show its kind - observation reports, instrumentation reports, benchmarks, the maintainer-ruling ledgers (finding decisions, tree-entry classifications), custom stack files. Read when a report, a benchmark, a custom stack file or a decision is persisted, recalled, shown or inventoried, or when a finding is declined (wontfix) or such a decision reversed, or a tree entry is ruled runtime or non-runtime; never invoked on its own.
otel-guides
Curated map of the official OpenTelemetry documentation by language. Use when planning or implementing OpenTelemetry instrumentation for a codebase - pick the language, open its reference file, and follow the linked official docs for traces, metrics, logs, instrumentation libraries, exporters, and SDK configuration. Covers C++, .NET, Erlang/Elixir, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Swift, and other community SDKs, plus the cross-language references for SDK configuration, semantic conventions, generative AI (the gen_ai conventions and the instrumentation library per LLM SDK or agent framework), the Collector, and profiling.
package-layout
Where this package is installed and what each part of it is - every skill, its reference files, its scripts, and the sibling directories the install carries. Use when a mission block needs the skills' directory, when a contract must name a reference or a script by path, or when anything is about to look for the package on disk. The answer comes from the script's own location, so it is exact wherever a host installed the package, and nothing has to be searched for or written down in advance.
test-plugin-harnessing
Measure and optimise one phase of an oddyssey run - preflight, drive, observation - against the published benchmark row for that model. Use when a phase is too slow or too expensive, when a harnessing change must be proven rather than asserted, or when a run is suspected of composing work the package should ship. Drives opencode headless, measures the phase, names where the time went, and separates what the package controls from provider latency. Never a substitute for launch-llms-benchmark, which grades findings; this grades the harness.
record-finding-decision
Record a maintainer decision (wontfix, ...) on a finding of a stored observation report into the committed ledger at .odd/decisions.md - the write that lets /odd-status stop rendering a declined finding as open. Use when the user declines a finding, marks it wontfix, or reverses such a decision. Never edits a report.
show-otel-instrumentation-report
Render a short synthesis of a persisted OpenTelemetry instrumentation investigation report for the human closing the mission - verdict-first headline, the stored path, the plan-at-a-glance table, the open decisions, and the recommended next action - never a replacement for the report itself. Use when an /odd-instrument-otel mission ends and the final answer must synthesize the stored report instead of dumping it raw.
update-backend-configuration
Own the backend switch of the global oddyssey configuration: verify the target backend's CLI is installed (offer a guided install when missing), persist the switch via odd_config_set, persist the per-stack stack_config values the missions will need, and hand back to check-backend-configuration for the connection proof. Stack-agnostic - the stack list and everything about a given stack come from the observability-cli-guides skill. Use when the user asks to change the configured stack/backend or to persist backend targeting values. Never installs silently, never authenticates on the user's behalf, never stores secrets.
create-update-benchmark
Persist a k6-benchmark-expert-authored benchmark (script + manifest) into .odd/benchmarks/<name>/ - naming, versioning, the commit, recalling the benchmarks already stored for a service. A benchmark is not a report - it is living source, updated in place via reviewed diffs, not append-only. Use when a benchmark's authored content needs to land in the repo, or when an update to an existing benchmark needs to be recalled before authoring a new one.
show-benchmark
Render a short synthesis of a persisted k6 benchmark for the human closing an /odd-instrument-bench mission - the stored path, what the benchmark exercises, the next recommended action - never a replacement for the script/manifest itself. Use when an /odd-instrument-bench mission ends and the final answer must synthesize what create-update-benchmark just stored instead of dumping it raw.
Bio shown is the top-scored skill's repo description as a fallback — real GitHub bios land in a future update.