Content
78%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-structured project-conventions skill: precise file/symbol-level guidance, clear step sequences with a test checkpoint, and exemplary progressive disclosure via a purpose-mapped references table. Weakest spots are the placeholder-bodied manager code template and slightly redundant prose around the singleton pattern.
Suggestions
Trim the manager-sample 'Key rules' bullets that restate the code (e.g. 'Use static let shared — never create multiple instances' is already evident from the sample), keeping only the non-obvious rules.
Replace the '{ ... }' placeholder bodies in the manager template with one small concrete example (e.g. an actual observer registration) so the pattern is fully executable.
Add one recovery line to the checklist, e.g. 'If the notch renders wrong in a state, check notchSize updates and the currentView switch before other causes.'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly all content is project-specific knowledge Claude cannot know (directory tree, three-layer state management, view composition map, pbxproj wiring). Minor over-explanation: the manager code sample's 'Key rules' bullets partially restate what the sample already shows, and the boilerplate Swift singleton scaffolding could be trimmed. Not level 5 ('every token earns its place') nor level 3 ('some unnecessary explanation' is only marginal here). | 4 / 5 |
Actionability | Highly actionable: exact files and symbols are named ('Constants.swift', 'enums/generic.swift', 'ContentView.NotchLayout()', 'scrollLocked set in handleUpGesture', 'needsTall check in onChange(of: currentView)'), and the settings-key snippet is copy-paste ready. Held at 4 rather than 5 because the manager pattern sample uses '{ ... }' placeholder bodies (template pseudocode) and 'func startMonitoring() { ... }' is not executable — minor gaps per the anchor. | 4 / 5 |
Workflow Clarity | Clear multi-step sequences exist for the main workflows ('Adding a New Setting', 'When adding a new top-level view', the 10-item 'Checklist for New Features') with an explicit validation checkpoint ('Test both open and closed notch states, and with liquid glass on/off'). Falls short of 5 because there is no error-recovery feedback loop (what to do when a step fails or a test reveals breakage); this is not a destructive/batch skill so no cap applies. | 4 / 5 |
Progressive Disclosure | The body is a genuine overview: a references table maps each of the six 'references/*.md' files (all verified to exist) to a 'When to read' condition, plus pointers to root ARCHITECTURE.md and BUILD.md. References are clearly signaled and one level deep — none of the reference files chain into further docs — matching the top anchor for easy navigation. | 5 / 5 |
Total | 17 / 20 Passed |