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.
The body is an exceptionally actionable coaching workflow: every step has verbatim prompts, exact option lists, validation gates, and a complete output template, with clear sequencing and error-recovery loops. Its weaknesses are repetition — re-run-mode rules and the 'never invent' rule each appear three times — and an inlined full file template that would fit better in a separate reference file.
Suggestions
Consolidate the re-run-mode rules (currently duplicated in 'Operating rules', Step 0 rule 4, and 'Re-run mode for support fields') into a single 'Re-run mode' section, and state the 'never invent' rule once at the top instead of three times.
Move the full App-Brief.md template (~65 lines in Step 5) to a references/ or assets/ file (e.g. references/app-brief-template.md) and keep only the required/optional field checklist inline in SKILL.md.
Trim the Step 2 instructions, which repeat the required/optional field lists twice within the same section (bulleted list plus the opening-message paragraph).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient domain-specific guidance, but the re-run-mode rules for existing App-Brief.md files are repeated nearly verbatim in three places (Operating rules bullet, Step 0 rule 4, and the 'Re-run mode for support fields' section), and 'never invent' is stated three times — clear cases where it could be tightened. It is above 2 because there is no explanation of concepts Claude already knows; the length comes from real domain content plus duplication. | 3 / 5 |
Actionability | Fully executable instruction-only guidance: verbatim challenge prompts per coached field, exact commands ("npx @cognite/cli@latest apps skills pull"), a sentinel glob pattern, fixed four-option supportPath choices, and a copy-paste-ready App-Brief.md template with exact YAML frontmatter. Specific examples (the shift-supervisor persona, the handover problem) cover the common cases. | 5 / 5 |
Workflow Clarity | The Preflight through Step 6 sequence is explicit, with validation checkpoints and feedback loops: the skills-pull sentinel check offers Retry/Skip/Stop, and Step 5 refuses to write the file and returns to coaching while any required field is empty. It also handles the re-run and edge cases (single maintainer warning, string-vs-list maintainer). Not a destructive or batch operation, so no cap applies. | 5 / 5 |
Progressive Disclosure | A single-file skill with no bundle directories, well-organized under numbered step headers and tables, and one clearly signaled one-level-deep reference ([start-flows-app](../start-flows-app/SKILL.md)). It is not a 5 because the ~65-line output template in Step 5 is content that could be split into a reference/asset file, keeping SKILL.md as a leaner overview. | 4 / 5 |
Total | 17 / 20 Passed |