Content
63%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 strong, information-dense reference with executable code, useful operational details (retries, idempotency, IP whitelisting), and explicit signature-verification checkpoints. Its main weaknesses are duplication (verify_signature x3, IP list x2) and a monolithic structure that inlines payload schemas and operation code that belong in reference files.
Suggestions
Extract the repeated signature-verification code into a single canonical implementation and remove the duplicate IP list, keeping one reference to it (improves conciseness).
Move per-event payload schema examples (auth, activity, sleep, daily, deauth) into a references/payloads.md and the operation implementations into references/operations.md, keeping SKILL.md as a concise overview with well-signaled one-level-deep links (improves progressive_disclosure).
Define or stub the undefined dependencies used in handler examples (db, logger, trigger_backfill, process_event) and fix the curl test example to include a valid signature or note that signature verification must be bypassed for local testing (improves actionability).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly dense Terra-specific reference material (event tables, payload examples, retry schedule), but includes notable duplication: the verify_signature code appears nearly verbatim three times (Quick Start, setup-webhook-endpoint, verify-signature operation) and the Terra IP list appears twice. Fits anchor 3 (mostly efficient but could be tightened) rather than anchor 4, where duplication would be only minor. | 3 / 5 |
Actionability | Concrete, mostly executable Flask/Celery/Mongo code with copy-paste-ready signature verification and handler dispatch. Minor gaps keep it below anchor 5: handlers reference undefined dependencies (db, logger, trigger_backfill, process_event), and the curl test example sends an unsigned payload its own code would reject with 401. | 4 / 5 |
Workflow Clarity | The Quick Start numbers its steps (verify signature → parse → handle → respond immediately) and includes an explicit validation checkpoint (401 on invalid signature) plus idempotency and retry handling for failure recovery. Below anchor 5 because there is no error-recovery loop for processing failures (e.g., what to do when a handler throws) and the setup-to-test sequence is implicit rather than laid out. | 4 / 5 |
Progressive Disclosure | Section headers are clear, but the ~560-line SKILL.md is monolithic with no references/ files: full payload schema examples and complete operation implementations that clearly belong in separate reference files are inlined. Matches anchor 3 (good structure, but content that should be separate is inline); anchor 4 would require most bulk content to live in external files. | 3 / 5 |
Total | 14 / 20 Passed |