Content
82%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, highly actionable skill body: concrete commands at every step, a clear 7-step workflow with sensible debug/verify checkpoints, and proper use of a one-level-deep canonical reference instead of inlining full scripts. The main costs are redundancy — the raw-launch guardrail and script-contract phrasing repeat across three sections plus the reference — and an implicit rather than explicit failure-recovery loop.
Suggestions
Consolidate the raw-executable-launch warning (currently in Workflow step 3, Guardrails, and references/build-script.md) into the single guardrail section, leaving the reference as the canonical source for launch mechanics.
Merge the Quick Start flag list with the Preferred Commands section — both enumerate the same './script/build_and_run.sh' variants, so one canonical list suffices.
Make the failure feedback loop explicit in step 5: after classifying the blocker, state 'fix the root cause and re-run ./script/build_and_run.sh' so the validate-fix-retry cycle is not left implicit.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with directives and assumes Claude's competence (no explanation of what Xcode, SwiftPM, or Info.plist are), delegating full script bodies to the reference. It is not a 5 because the kill-build-run contract and the raw-executable-launch warning ('Do not recommend direct SwiftPM executable launch...' / 'Do not launch a SwiftUI/AppKit SwiftPM GUI app as a raw executable...') are repeated across Quick Start, Workflow step 3, Guardrails, and the reference, and the Quick Start flag list duplicates the Preferred Commands list. | 4 / 5 |
Actionability | Concrete executable commands appear throughout: 'find . -name '*.xcworkspace' -o ...', 'xcodebuild -list -workspace <workspace>', './script/build_and_run.sh --telemetry', exact Info.plist keys, 'pgrep -x <AppName>', and 'NSApp.setActivationPolicy(.regular)'. The full copy-paste-ready scripts live one level deep in references/build-script.md, covering both common cases (SwiftPM CLI and GUI). This matches anchor 5; anchor 4 would imply missing key details that are instead all present across body plus reference. | 5 / 5 |
Workflow Clarity | The 7-step workflow is clearly sequenced — discover shape, resolve target, create script, build/run, classify failures, debug, use MCP — with concrete checkpoints like '--verify' to 'confirm the process exists with pgrep -x <AppName>' and failure classification in step 5. It stops short of anchor 5 because the validate-fix-retry feedback loop is implicit rather than explicit: there is no 'fix and re-run' step after classifying a blocker, so a validation gap remains. | 4 / 5 |
Progressive Disclosure | Structure is good: a one-level-deep, clearly signaled reference ('references/build-script.md: canonical script/build_and_run.sh shapes...') that is explicitly designated the canonical source, and it is a real file in the bundle. Not a 5 because the body still inlines script-shape detail that also lives in the reference (plist keys, open -n launch details, activation-policy advice appear in both), leaving minor duplication that could be consolidated. | 4 / 5 |
Total | 17 / 20 Passed |