maple-telemetry-conventions

Maple's OpenTelemetry conventions — custom span attribute keys (`maple.*` vendor namespace, `query.context`, `db.query.*`, `result.*`, `cache.*`, `tenant.*`), Title Case status codes (`Ok`/`Error`/`Unset`), resource attribute dual-emit (`deployment.environment` + `deployment.environment.name`), span kinds, Tinybird MV pre-extracted columns, loop-prevention filters, and sampling. Use whenever writing or reviewing instrumentation code in any language (TypeScript, Rust, Python) in this repo — adding `setAttribute`/`setAttributes`/`record`/`#[instrument(fields(...))]` calls, setting span status, configuring an OTLP exporter, defining a new resource attribute, or wiring a new query through `WarehouseQueryService.compiledQuery()`.

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/maple-telemetry-conventions/SKILL.md

Quality

Content

60%Weight 40%Scale 1-5

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

A well-organized, information-dense reference whose inline quick-reference and canonical repo citations are valuable, but its core detailed content is deferred to seven rules/*.md files that are not present in the skill bundle, undermining both actionability and navigation.

Suggestions

Ship the seven referenced rules/*.md files (or at least rules/span-attributes.md and rules/language-bindings.md) inside references/ so the deferred detail is actually reachable.

Add a small inline executable code snippet (one TypeScript + one Rust setAttribute/status example) so the common case is actionable without opening a bundle file.

Trim overlap between the Quick reference table and the Canonical references list (e.g. loop-prevention and deployment-env appear in both) to tighten conciseness.

Dimension	Reasoning	Score
Conciseness	Mostly lean and efficient — dense tables, bullets, and file:line citations that assume Claude's competence, with Maple-specific context that is not generic fluff. Minor redundancy between the Index, Quick reference table, and Canonical references sections could be trimmed.	4 / 5
Actionability	Concrete conventions are stated (exact status strings, exact attribute keys, namespace rules), but all executable code is deferred to rules/language-bindings.md and rules/span-attributes.md — files that are referenced but not present in the bundle — leaving key implementation details missing.	3 / 5
Workflow Clarity	A well-organized reference skill with a clear 'When to apply' trigger list and an Index mapping each concern to its rule file; the single lookup-then-apply flow is unambiguous. No validation checkpoint is needed for a non-destructive reference skill, but the lookup depends on missing rule files.	4 / 5
Progressive Disclosure	The structure is well-signaled in concept (a clear one-level-deep Index pointing to 7 rules/*.md files), but none of those referenced bundle files exist in references/scripts/assets, so the promised detailed content is unreachable and the skill cannot actually deliver its details.	2 / 5
	Total	13 / 20 Passed

Description

92%Weight 40%Scale 1-5

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

A strong, specific description that explicitly covers both what and when with concrete trigger phrases and minimal conflict risk. It leans somewhat on internal jargon, which slightly limits natural trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain (Maple's OpenTelemetry conventions) and lists multiple concrete actions — adding setAttribute/record calls, setting span status, configuring an OTLP exporter, defining a resource attribute, wiring a query through compiledQuery() — with comprehensive coverage.	5 / 5
Completeness	Explicitly answers both what (the full convention surface: attribute keys, Title Case status, dual-emit, span kinds, MV columns, loop-prevention, sampling) and when ('Use whenever writing or reviewing instrumentation code... — adding... setting... configuring... defining... or wiring...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good coverage of natural developer triggers ('writing or reviewing instrumentation code', 'OTLP exporter', 'span status', 'resource attribute') and concrete API names, but leans heavily on internal jargon (maple.*, Tinybird MV, compiledQuery) and omits common synonyms like 'tracing' or 'telemetry'.	4 / 5
Distinctiveness Conflict Risk	A clear, narrow niche (Maple-specific OTel conventions) with highly distinct triggers (maple.* namespace, Tinybird MV columns, WarehouseQueryService.compiledQuery) and minimal overlap with any other skill.	5 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

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

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: MapleTechLabs/maple
Path: .agents/skills/maple-telemetry-conventions/SKILL.md
Commit: 6d47ff3

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.