Content
61%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 well-structured, actionable overview of Square workflows with concrete tool sequences, but it is held back by redundant pitfalls, a filler 'When to Use' line, and missing validation feedback loops for destructive operations.
Suggestions
Add explicit validate→fix→retry checkpoints to destructive workflows (e.g., for UPDATE_ORDER/CANCEL_INVOICE: fetch current version, attempt the call, and on a 409 re-fetch and retry rather than just warning about version mismatches).
Remove redundant pitfalls — keep each pitfall in one place (either per-workflow or in 'Known Pitfalls', not both) and delete the filler 'When to Use' line.
Consider moving the per-workflow 'Key parameters' detail and 'Quick Reference' table into a reference file so SKILL.md stays a lean overview pointing one level deep.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient with well-organized sections, but pitfalls are repeated across 'Core Workflows' and 'Known Pitfalls', and the trailing 'When to Use' section ('This skill is applicable to execute the workflow or actions described in the overview.') is pure filler that could be trimmed. | 3 / 5 |
Actionability | Provides concrete tool sequences with exact slugs (e.g., 'SQUARE_LIST_PAYMENTS'), named parameters, and formats (RFC 3339), giving mostly executable guidance with only minor gaps like missing example call payloads. | 4 / 5 |
Workflow Clarity | Setup and each workflow are clearly sequenced with a setup checkpoint ('Confirm connection status shows ACTIVE'), but destructive operations (cancel payment, cancel invoice, update order) lack explicit validate→fix→retry feedback loops, capping workflow clarity at 3. | 3 / 5 |
Progressive Disclosure | Well-structured single-file overview with clear section navigation (Prerequisites, Setup, Core Workflows, Common Patterns, Known Pitfalls, Quick Reference) and no nested references; minor organization gaps since some detail could live in reference files. | 4 / 5 |
Total | 14 / 20 Passed |