Conciseness

The body is dense with non-obvious operational facts Claude cannot know (retention limits, the epoch-nanosecond arithmetic because "the bundled DuckDB does not support TIMESTAMPTZ - INTERVAL", the 50 KB body-capture cap, "Refetching replaces whole records in DuckDB, clearing omitted fields") and explains nothing Claude already knows. It falls just short of the top anchor because a few sections — notably "Query JSON body fields" and the consumers example appearing as both a CLI command and SQL — partially duplicate content already covered in the reference files and could be trimmed.

Actionability

Every workflow step and investigation pattern ships a fully executable command or SQL statement with realistic flag values, e.g. the metrics command with '--metrics '["requests","error_rate","response_time_p50","response_time_p95"]' --group-by '["method","path"]' --interval day --db' and the span query with 'epoch_ns(current_timestamp) - 86400000000000'. Filter JSON shapes, join keys, and exit-code recovery actions are all concrete and copy-paste ready, matching the top anchor; there are no pseudocode or placeholder gaps.

Workflow Clarity

The six-step Investigation Workflow is clearly sequenced (identify app → time range → supporting data → fetch → query DuckDB → iterate) with explicit error-recovery loops: "If any command exits with code 3 (auth error), ask the user to run npx @apitally/cli auth", the legacy-schema recovery path requiring preservation or user permission before the destructive reset-db, and step 6's refine/refetch loop. Consistency rules ("Use this time range consistently... and SQL WHERE conditions") act as checkpoints, matching the anchor for explicit validation and feedback loops; the score-4 anchor's "minor validation gaps" does not apply.

Progressive Disclosure

SKILL.md is a genuine overview: a brief command quick-reference inline, with the bulk (412-line command reference, DuckDB table schemas, JSON functions) split into three one-level-deep reference files that all exist and are clearly signaled with purpose descriptions ("full flags, fields, filters, and operators", "column types, relationships, and special types"). Anchored deep links like references/commands.md#traces resolve to real sections, matching the top anchor for well-signaled, appropriately split content.

Specificity

The description lists multiple concrete actions — "Fetches aggregated metrics, request logs, traces, consumers, and app metadata via the CLI", "stores data in a local DuckDB database", and "runs SQL queries to investigate issues or answer questions" — covering the skill's full capability set in third-person voice. This matches the anchor for comprehensive concrete actions; the score-4 anchor ("minor gaps in coverage") does not apply since fetching, storing, and querying are all named.

Completeness

It explicitly answers both questions: the "what" is three sentences of concrete capabilities, and the "when" is an explicit trigger clause ("Use when the user mentions Apitally, the Apitally CLI, API metrics, request logs, traces, or API consumers"). This is a direct match for the top anchor; the 4 anchor's caveat ("'when' could be more explicit") does not apply.

Trigger Term Quality

Triggers are natural and well-chosen ("Apitally, the Apitally CLI, API metrics, request logs, traces, or API consumers") but a few phrases a user would plausibly say are missing, such as "API monitoring", "error rates", or "slow endpoints". This fits the anchor for good keyword coverage with a few natural terms missing rather than the comprehensive synonym coverage of a 5.

Distinctiveness Conflict Risk

"Apitally" is a distinct brand name anchoring the trigger clause, and the supporting terms (Apitally CLI, Apitally metrics) are all product-specific, giving the skill a clear niche with minimal conflict risk against generic SQL, database, or logging skills. It matches the "clear niche with distinct triggers" anchor.