Content
88%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 well-engineered instruction skill: hard rules, blocked-pattern table, ordered protocol with a file-verification checkpoint, and a genuinely useful troubleshooting table, all delegating code patterns to canonical docs and one-level-deep references. The two real defects are the broken reference-link hrefs and recurring restatements of the same mandates that cost tokens without adding guidance.
Suggestions
Fix the reference link hrefs to relative paths — they currently point to https://docs.stripe.com/references/<file> (e.g. change [references/discovery.md](https://docs.stripe.com/references/discovery.md) to [references/discovery.md](references/discovery.md)) so navigation resolves to the local bundle files.
State the WebFetch-the-canonical-docs mandate once (e.g. in Hard Rule 4) and reference it elsewhere, instead of repeating the full instruction in the 'Source of truth' section, Step 3, and the reference table.
Compress the 'Your role' persona prose ('You are a PROJECT BUILDER and INSTRUCTOR... You are also a patient guide') into the two operative directives (write files to disk; explain in plain language), cutting redundant tokens from the always-loaded body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and directive (tables for hard rules, blocked patterns, architecture→file mapping, troubleshooting) with no explanation of concepts Claude already knows, but it repeats the docs-first mandate four times ("Source of truth" section, Hard Rule 4, Step 3 intro, the reference table) and carries persona prose ("You are a PROJECT BUILDER and INSTRUCTOR... You are also a patient guide") that could be trimmed. | 4 / 5 |
Actionability | Commands are copy-paste ready (`stripe generate app <name>`, `pnpm build`, `stripe apps upload`), filenames are exact (`ui/src/views/App.tsx`, `server.js`), the discovery questions and user-facing summary template are given verbatim, and the architecture table maps each answer set to the exact files to modify or create. Code samples are deliberately delegated to WebFetch'd canonical docs plus reference files, which is an explicit, justified design rather than a gap. | 5 / 5 |
Workflow Clarity | The Protocol is a strictly ordered 5-step sequence (discover → confirm → scaffold → build → deliver) with an explicit validation checkpoint (Step 5: `ls` the written files, re-Write any missing one), a required user confirmation gate before scaffolding, and a troubleshooting table mapping upload errors to fixes — feedback loops and checkpoints are all present. | 5 / 5 |
Progressive Disclosure | The overview stays lean and the 13 reference files are all real, one level deep, and indexed in a "read when" table — but the markdown link hrefs are wrong: every link points to `https://docs.stripe.com/references/<file>` instead of the relative local path (e.g. `[references/discovery.md](https://docs.stripe.com/references/discovery.md)`), so clicked navigation breaks and only the backtick plain-text paths resolve. | 4 / 5 |
Total | 18 / 20 Passed |