Content
81%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 procedure with real validation and feedback loops — the cross-file invariants it exists to enforce are all captured concretely. Its weaknesses are verbosity (the same gotchas restated across procedure, verification, and failure-modes sections, plus incident-history anecdotes) and two missed progressive-disclosure opportunities (an orphaned references/railway.md and inline-able worked examples).
Suggestions
State each gotcha once: the scopeMap hard-coded count, dashboard paste-token allowlist, TRANSPORT typo, and gitignored-catalog points each appear in 2–4 sections at full length — keep the full explanation in the procedure step and reduce the Failure modes / step 9 entries to one-line pointers.
Extract the HubSpot OAuth worked example and the 'When another connector lands first' merge-conflict guide into reference files (e.g. references/oauth-setup.md, references/rebase-conflicts.md) and link them one level deep, mirroring how translation.md is gated on porting.
Reference the existing references/railway.md from the body (it is currently orphaned — never mentioned, so its content is undiscoverable) and add it to the File layout section's references/ listing.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body (~39KB) never explains concepts Claude already knows — nearly every line carries repo-specific invariants — but the same gotchas are restated at full length in multiple sections: the scopeMap hard-coded count appears in step 5a, step 8, the rebase section, and Failure modes; the dashboard paste-token allowlist in step 5f and Failure modes; the TRANSPORT typo and gitignored-catalog points likewise each appear twice or more, and incident-history anecdotes ("we hit exactly this gap with HubSpot", "#63/#68", "16 conflicts in one observed pass") pad the prose. Mostly efficient but could be tightened by stating each gotcha once and cross-referencing. | 3 / 5 |
Actionability | Fully executable throughout: exact file paths, copy-paste command blocks (`git clone --depth 1`, `npm run typecheck`, `node scripts/buildMcpToolsDoc.mjs`, `git worktree add /tmp/mainwt origin/main --detach`), complete code snippets for the `createMcpCatalog` block and both catalog JSON shapes, the exact test assertions to add, and explicit template-to-output file mappings. Placeholders are parameterized (`<slug>`, `{{slugCamel}}`), which is appropriate for a scaffold skill. | 5 / 5 |
Workflow Clarity | Nine clearly sequenced steps with abort-early uniqueness checks, input validation (slug regex, ask-if-missing), an explicit verification step (typecheck + test) with named failure modes and remediation, and genuine feedback loops: fix-and-re-run test guidance, "Reproduce on unmodified main before touching anything" for suspected environmental hangs, and explicit prohibitions ("Don't reach for `as any`"). The report step ends with a checklist of manual follow-ups. | 5 / 5 |
Progressive Disclosure | Good structure: templates are externalized to `assets/` (all five referenced files exist), `references/translation.md` is gated ("read only when porting from a github-url"), references are one level deep, and the File layout section documents the bundle. Two gaps keep it from 5: `references/railway.md` exists in the bundle but is never referenced from SKILL.md or listed in the File layout (orphaned, undiscoverable), and the HubSpot OAuth worked example plus the merge-conflict resolution guide are substantial self-contained topics inlined in the body that belong in reference files. | 4 / 5 |
Total | 17 / 20 Passed |