Content
70%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.
The body is a highly actionable, well-sequenced internal-integration playbook with genuine validation gates and a strong checklist. Its weaknesses are structural: it is a monolithic single file where polling and handler references belong in separate bundle files, and it carries duplicate handler examples plus a checklist that repeats earlier content.
Suggestions
Split the Polling Triggers and Provider Handler sections into one-level-deep reference files (e.g. references/polling.md, references/handler.md) and keep SKILL.md as the overview plus the core webhook path.
Merge the two {service}Handler code blocks into one example that shows verifyAuth/matchEvent/formatInput alongside createSubscription/deleteSubscription to remove the duplicated handler declaration.
Trim the checklist entries that literally restate body sections (keep only the checklist-native items like validation commands) to reduce token cost without losing coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The code templates are Sim-specific infrastructure Claude cannot know, so most tokens earn their place; however, the {service}Handler is declared in two separate example blocks and the ~50-line checklist largely restates earlier sections. This lands on anchor 3 (mostly efficient but could be tightened) rather than 4 because the duplication is real, not just minor. | 3 / 5 |
Actionability | Concrete and executable throughout — exact file paths, adaptable TypeScript templates, real commands (bun run type-check, helm values.yaml), with placeholders explicitly justified by argument-hint. A few examples are abbreviated ("Same as above but...", "// Fetch changes since last poll"), keeping it at anchor 4 rather than fully copy-paste-ready 5. | 4 / 5 |
Workflow Clarity | A clearly sequenced workflow (research → create files → register → wire → handler → checklist) with explicit validation steps (type-check, manual output-key verification, running generate-docs.ts and verifying the result, CI docs:check guard) and a hard decision gate with four fallback options for unknown payloads. This matches anchor 5: clear sequence, explicit checkpoints, and a checklist. | 5 / 5 |
Progressive Disclosure | The file is well-sectioned with clear headers, but all ~570 lines live in SKILL.md with no bundle files at all — the polling guide, provider-handler reference, and option-lists rules are prime candidates for one-level-deep reference files. This fits anchor 3 (content that should be separate is inline); not 4 because nothing is split out. | 3 / 5 |
Total | 15 / 20 Passed |