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.
A highly actionable, well-sequenced coaching skill: concrete commands, a complete output template, explicit validation gates, and feedback loops at every failure point. Its only notable weakness is redundancy — the opening-move rule and the batch-confirmation rule are each stated twice — plus a template block that could arguably be a reference file in an otherwise lean single-file body.
Suggestions
Remove the duplicated guidance: keep the "write the brief after the SME conversation / do not dump an empty template" rule in one place (the intro) and delete its restatement in Operating rules; likewise consolidate the batch-confirmation rule from Operating rules bullet 2 with the near-identical paragraph closing the Spec-kit mapping section.
Consider moving the full App-Brief.md template block (Step 4) into a reference file (e.g. references/app-brief-template.md) and keeping only the required/optional field list inline, so the body stays a lean overview with one clearly signaled reference.
Trim the repeated preflight options between the blockquote ("Pull / Skip") and the numbered recovery path ("Retry / Skip and continue / Stop") so each choice and consequence is stated exactly once.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient and free of concept over-explanation, but real duplication exists: the "do not dump an empty template as the opening move" / "write the brief after the SME conversation" rule appears both in the intro paragraph and in Operating rules, and the batch-confirmation guidance for spec-derived drafts is stated twice in near-identical words (Operating rules bullet 2 and the close of Spec-kit mapping). Not 4 because these are more than minor trimmings — whole sentences and one full bullet are redundant; not 2 because there is no padding or teaching of known concepts and every section carries functional weight. | 3 / 5 |
Actionability | Fully executable guidance throughout: exact commands (`npx @cognite/cli@latest apps skills pull`, `Glob '**/skills/correctness-and-error-handling/SKILL.md'`), a complete copy-paste-ready App-Brief.md template with exact YAML frontmatter, scripted challenge questions in quotes, concrete good examples for each coached field, and the exact closing message. Matches the anchor for copy-paste-ready, specific examples covering common cases. | 5 / 5 |
Workflow Clarity | Clear Step 0–5 sequence with explicit validation checkpoints and feedback loops: the preflight sentinel glob with "Zero matches → ask: Retry / Skip and continue / Stop", challenge-and-re-ask loops per coached field, and the hard gate "If any required field is still empty, do not write the file — return to coaching that field". Error recovery paths are explicit at every failure point. | 5 / 5 |
Progressive Disclosure | Well-organized single-file structure with clear section headers, and the one external reference ([start-flows-app](../start-flows-app/SKILL.md)) is well-signaled and one level deep; no bundle files exist so nothing is buried. Not 5 because at ~215 lines some self-contained blocks (e.g. the 55-line output template, the field-by-field coaching rubric) could live in a reference file to keep the SKILL.md body a leaner overview; not 3 because nothing that clearly belongs elsewhere is inlined and navigation is easy. | 4 / 5 |
Total | 17 / 20 Passed |