Content
88%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A high-quality operational skill: it assumes Claude's competence, carries only verifiable vendor-specific behavior, and provides copy-paste-ready code for all three surfaces with a real verification step and diagnostic feedback loops. The main weaknesses are version-sensitive details embedded in the mainline steps and a long inline Reference notes section that could live in a separate file.
Suggestions
Move the 'Reference notes (for explaining results to the user)' section into a references/ file (e.g. references/span-map.md) and link it one level deep, keeping SKILL.md as the step-by-step overview.
Collect the minimum-version requirements (SDK >= 0.3.283 / >= 0.2.160, CLI >= 2.1.283) into a single pinned 'Version requirements' block so version-rot is isolated and easy to update, rather than repeating them across Steps 0, 2c, and 5.
The near-duplicate 15-variable OTEL env lists in Step 2a, 2b, and 2c could be presented once as a variable table, with each surface showing only its container format (TS object / Python dict / settings JSON).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious vendor facts and never explains concepts Claude already knows (e.g. 'the Agent SDK emits nothing itself. query() spawns the Claude Code CLI', the TS 'REPLACES' vs Python 'MERGES over the inherited env' distinction, settings-precedence rules). However, the rubric directs a penalty for time-sensitive details outside an 'old patterns'/'deprecated' section, and version-bound facts are woven throughout the steps ('Need >= 0.3.283 (bundles Claude Code 2.1.283)', 'Claude Code >= 2.1.282 ignores the vars', 'Claude Code 2.1.283 may run Agent calls in the background'), so it sits between 'efficient' (4) and 'every token earns its place' (5). | 4 / 5 |
Actionability | Fully executable, copy-paste-ready guidance per surface: complete `maple-env.ts` and `maple_env.py` modules, a mergeable `~/.claude/settings.json` block, TS and Python session-resume patterns, exact endpoints and headers ('https://ingest.maple.dev', 'Authorization=Bearer <key>'), install commands, and verification commands ('claude --debug-file /tmp/claude.log, then grep 3P telemetry'). These cover the common cases with concrete code rather than hints. | 5 / 5 |
Workflow Clarity | Steps 0-7 are clearly sequenced (Detect, Key/region, per-surface setup, Session boundary, Content, Tools/errors, Flush, Verify) with an explicit validation phase: Step 7 prescribes a two-turn one-tool test run, a checklist of expected Maple outcomes, and feedback loops for error recovery ('If spans exist but the turn nests under an unrelated trace, an inherited TRACEPARENT survived: fix the env stripping', 'A 401 ... usually means the key belongs to the other region: try the other endpoint'). | 5 / 5 |
Progressive Disclosure | The single file is well-organized with meaningful headers ('Step 0: Detect' through 'Step 7: Verify', 'Reference notes', 'Do not') and no nested or dead references, and no bundle files exist to navigate. But at ~250 lines it exceeds overview scale, and the 'Reference notes (for explaining results to the user)' section (~15 dense bullets on span maps, token counting, cost, and truncation) is reference material inlined in SKILL.md rather than split into a one-level-deep referenced file - 'good structure; minor organization gaps' rather than a clear overview pointing to detail. | 4 / 5 |
Total | 18 / 20 Passed |