CtrlK
BlogDocsLog inGet started
Tessl Logo

kopai/root-cause-analysis

Investigate and root-cause production issues from live OpenTelemetry telemetry (traces, logs, metrics) with the Kopai SDK in TypeScript code mode. Use this skill to debug errors and error-rate spikes, investigate latency/slowness and timeouts, trace requests across services, find failing or cascading services, and correlate logs to a trace — including vague symptom reports like 'why is my API slow', 'getting 500 errors', 'service is down', 'requests are timing out', or 'something is failing in prod', even when the user never says 'traces' or 'observability'. This analyzes existing telemetry to find a cause. Do NOT use it to add instrumentation (use otel-instrumentation), to build dashboards or visualizations (use create-dashboard), or to fix non-telemetry problems like failing CI, lint errors, unit tests, or SQL query tuning.

77

Quality

97%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Overview
Quality
Evals
Security
Files

Quality

Content

92%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A high-quality, executable skill body: lean non-obvious API knowledge, copy-paste TypeScript, a sequenced workflow with re-check checkpoints, and one-level-deep references. The main gap is the missing 'rules/' directory referenced repeatedly in the body, which leaves some signaled navigation pointing at files that don't exist.

Suggestions

Add the missing 'rules/' directory with the workflow-* and pattern-*.md files referenced in the Rules section, or remove/inline those references so no signaled navigation points at nonexistent files.

Collapse the 'Quick Example' section, which duplicates the workflow step-1 query, or relabel it to add incremental value beyond the RCA Workflow example.

Consider moving the dense 'Backend caveats & gotchas' list into a reference file (e.g. references/gotchas.md) to keep SKILL.md as a leaner overview while preserving the detail one level deep.

DimensionReasoningScore

Conciseness

The body is dense with Kopai-specific, non-obvious knowledge Claude lacks (StatusCode 'Unset'|'Ok'|'Error' semantics, service.name vs ServiceName trap, percentile ClickHouse-only limits, Duration nanosecond reporting, search* async-iterable gotchas) and assumes TS competence without explaining basic concepts. Not a 2 because there is no generic padding or explaining-of-known-concepts; the only minor redundancy (the Quick Example echoing the workflow step-1 query) is not enough to drop it below the 'every token earns its place' anchor.

3 / 3

Actionability

Fully executable TypeScript throughout — 'const client = clientFromConfig()', 'npx tsx rca.mts', complete kq query chains ending in '.build()' and 'await client.query(q)', plus try/catch on 'KopaiQueryBuildError' and concrete CLI fallback commands. Not a 2 because the examples are complete and copy-paste ready rather than pseudocode or missing key details.

3 / 3

Workflow Clarity

A clearly sequenced 5-step RCA Workflow (find failing work → get trace context → correlate logs → quantify impact → present findings), each with executable code and an explicit error-recovery loop ('if (e instanceof KopaiQueryBuildError) ... else throw e'). The gotchas section supplies a feedback checkpoint — 'Empty result on a busy system ≈ a wrong column/value, not real absence ... re-check ... before concluding all healthy'. Not a 2 because validation/re-check checkpoints are explicit rather than missing or implicit.

3 / 3

Progressive Disclosure

The overview points to three real one-level-deep references (trace-filters.md, log-filters.md, metric-filters.md) and signals a rules/ tree ('Read rules/<rule-name>.md for details'), but the referenced 'rules/' directory and its workflow-*/pattern-* files do not exist in the bundle. Per the guideline to score against the actual bundle structure, the broken rule references keep this below the 'easy navigation' anchor. Not a 1 because the existing references are well-signaled and one level deep, and the main content is reasonably split rather than a monolithic wall.

2 / 3

Total

11

/

12

Passed

Description

100%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

An excellent description: concrete capabilities, natural-language and vague-symptom triggers, explicit what-and-when guidance, and clear negative boundaries against sibling skills. Third-person voice is maintained, so no specificity penalty applies.

DimensionReasoningScore

Specificity

Lists multiple concrete actions — 'Investigate and root-cause', 'debug errors and error-rate spikes', 'investigate latency/slowness and timeouts', 'trace requests across services', 'find failing or cascading services', and 'correlate logs to a trace' — matching the 'multiple specific concrete actions' anchor. It is not a 2 because the actions are enumerated comprehensively rather than naming only the domain.

3 / 3

Completeness

Explicitly answers both what ('Investigate and root-cause production issues from live OpenTelemetry telemetry') and when ('Use this skill to debug errors ... including vague symptom reports ... even when the user never says traces or observability'). Not a 2 because the 'Use when' trigger guidance is explicit, not merely implied.

3 / 3

Trigger Term Quality

Quotes natural phrases users actually say — 'why is my API slow', 'getting 500 errors', 'service is down', 'requests are timing out', 'something is failing in prod' — plus technical variants ('errors', 'error-rate spikes', 'latency/slowness'), giving strong coverage of common variations. Not a 2 because it goes beyond 'some relevant keywords' to include the vague symptom phrasings.

3 / 3

Distinctiveness Conflict Risk

Occupies a clear niche (telemetry-based RCA) and disambiguates from siblings via negative triggers — 'Do NOT use it to add instrumentation (use otel-instrumentation), to build dashboards or visualizations (use create-dashboard), or to fix non-telemetry problems like failing CI, lint errors, unit tests, or SQL query tuning'. Unlikely to trigger for the wrong skill; not a 2 because the conflict boundaries are explicit.

3 / 3

Total

12

/

12

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation16 / 16 Passed

Validation for skill structure

No warnings or errors.

Reviewed

Table of Contents