Content
68%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.
An exceptionally dense, high-signal style guide: nearly every sentence encodes a Maple-specific rule or semantic-convention key Claude would not otherwise know, backed by an executable reference pattern. Its main weakness is structural — it is a topic reference rather than a sequenced onboarding workflow, leaving step order and the smoke-check validation implicit and dependent on the external `maple-onboard` skill.
Suggestions
Add a short ordered overview at the top (1. bootstrap endpoint/key and resource attributes → 2. instrument business spans → 3. provider instrumentation for LLM calls → 4. smoke check) so the workflow is explicit rather than inferred from section order.
Make the smoke check a real validation loop — specify what failure looks like (no OTLP export attempt, duplicate processors, instrumentation version mismatch) and what to do about it — rather than a conditional suggestion to skip it.
Tighten the "Cost" paragraph (split the OpenRouter include-flag case into its own sentence) and merge the duplicate "do not invent parallel attributes" guidance into one place to earn the top conciseness anchor.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and imperative throughout — "Do not shell out to `git` from the running process", "skipping the SHA is fine, skipping the URL is not" — and adds only Maple-specific policy Claude would not know (session grouping by `maple_ai.session.id`, OpenInference double-recording, cost-attribute placement rules). Not a 5: the "Cost" paragraph is a long run-on covering many cases, and "do not invent parallel attributes" is stated twice (Naming and VCS sections). | 4 / 5 |
Actionability | The business-span section gives a complete, copy-paste-ready TypeScript example with correct try/catch/finally structure, and later sections name exact keys (`vcs.repository.url.full`, `gen_ai.usage.cost`, `maple_ai.session.id`), env vars (`VERCEL_GIT_COMMIT_SHA`, `GITHUB_SHA`), and metric names (`llm.tokens.input`). Minor gaps keep it below 5: the exporter setup is deferred ("each language skill shows the exact shape") and the endpoint block is a placeholder (`maple_pk_…`) rather than executable init code. | 4 / 5 |
Workflow Clarity | The content is organized by topic, not by an explicit onboarding sequence; the implied order (naming → endpoint/key → resource attributes → signals → LLM calls → smoke checks) must be inferred, and it references external workflow steps ("`maple-onboard` Step 0", "the Step 4 run") without mapping them. The single validation checkpoint — the smoke check — is real but conditional ("If it has none, skip it; the Step 4 run is enough") and has no fix-and-retry feedback loop. | 3 / 5 |
Progressive Disclosure | A single, well-sectioned ~130-line file with clear headers and no nested or buried references; there are no bundle files (no references/, scripts/, or assets/), and nothing clearly belongs in a separate file at this size. Below 5 because it exceeds the under-50-line simple-skill threshold and the long LLM section (instrumentation choice, cost, conversations, redaction) is the one candidate that could split into a reference if the skill grows. | 4 / 5 |
Total | 15 / 20 Passed |