Content
85%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 actionable, well-sequenced orchestration skill with concrete commands, paths, templates, and explicit validation loops. Its weaknesses are length and structure: prose passages could be tightened, and large topical sections (file handling, icon theming, V2) should be split into reference files rather than inlined in the main skill body.
Suggestions
Move the File Handling section (~170 lines) and the icon theme-safety rules into reference files (e.g. references/file-handling.md, references/icon-theming.md), leaving one-line pointers in SKILL.md.
Convert the multi-paragraph credential-lifecycle, secret-coordination, and migration prose in Step 1 into checklist bullets to cut tokens while preserving the rules.
Merge the Step 8 validation commands into the Final Validation checklist to remove the duplicated regenerate/check instructions.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, rule-first, and never explains concepts Claude already knows (no "what is OAuth" padding; every section is directive). It is not a 5 because long prose passages — "Verify the complete lifecycle, including connect-time verification, concurrent executions..." and the migration-authorization paragraphs — could be tightened into checklist bullets without losing content. | 4 / 5 |
Actionability | Fully actionable throughout: exact file paths (`apps/sim/lib/internal/tool-operations/registry.server.ts`), runnable commands (`bun run generate:tool-metadata`, `bun run check:tool-request-boundary`, `bun run check:bare-icons`), registry/icon/mdx code templates, and a helper-location table. The `{service}` placeholders are justified scaffold parameters, not pseudocode, and cover the common cases. | 5 / 5 |
Workflow Clarity | Eight explicitly ordered steps with per-step validation commands, a Step 8 regenerate-and-check loop, a Final Validation checklist, and explicit error-recovery paths (the Hard Rule offers four concrete fallbacks when response schemas are unknown, including "Leave the tool unimplemented and explicitly report why"). Checkpoints and feedback loops are explicit, not implicit. | 5 / 5 |
Progressive Disclosure | References to sibling skills (`.agents/skills/add-tools/SKILL.md`, `add-block`, `add-trigger`, `add-selector`, `validate-integration`) are clearly signaled one level deep with what to find in each, but the SKILL.md itself inlines large self-contained chunks — the ~170-line File Handling section, the icon theme-safety rules, and the V2 pattern — that belong in reference files. This matches the anchor where content that should be separate is inline; good signaling and section structure keep it above 2. | 3 / 5 |
Total | 17 / 20 Passed |