Content
70%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 operationally precise, well-sequenced workflow with strong validation gates and error recovery around a destructive archive move — its strongest qualities. Its weaknesses are redundancy (Guardrails and repeated sync rules restate step content) and a monolithic structure that inlines a long sync contract which belongs in a one-level-deep reference file.
Suggestions
Extract the step 4 delta-spec sync contract (missing-main-spec branching, retire_capabilities handling, and the post-sync structural verification checklist) into a references/ file (e.g. references/sync-contract.md) and link to it from the step, keeping SKILL.md as the overview.
Remove the Guardrails entries that restate in-step rules verbatim (e.g. the inline-sync and never-archive-in-flight rules already fully specified in step 4), keeping only genuinely additional guardrails.
Consolidate the twice-stated REMOVED-only / retire_capabilities rules into a single stated-once rule covering both the assessment and the verification pass, eliminating the repeated 'apply this rule both now and when verifying' phrasing.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is composed almost entirely of non-obvious operational contracts (store stickiness, root-null branching, sync-blocked rules) rather than concepts Claude already knows, but it could be meaningfully tightened: the Guardrails section restates rules already given in the steps (the inline-sync instruction appears in both step 4 and Guardrails), the REMOVED-only/retire_capabilities rules are stated twice ('Apply this rule both now and when verifying a completed sync'), and the prose is densely repetitive. This lands on anchor 3 ('mostly efficient but... could be tightened') rather than 4, where only minor trimming would be needed. | 3 / 5 |
Actionability | Concrete, executable commands are given for the key operations — 'openspec instructions archive --change "<name>" --json', 'openspec status --change "<name>" --json', 'mkdir -p "<planningHome.changesDir>/archive"', 'mv "<changeRoot>" ...' — with the exact JSON fields to read (root, totalTasks, artifactPaths). It is not anchor 5 because the sync assessment, merge, and verification steps describe semantics and structural rules without commands or examples, relying on delegation to the openspec-sync-specs workflow. | 4 / 5 |
Workflow Clarity | The six steps are clearly sequenced with explicit validation checkpoints and feedback loops around a destructive operation: artifact and task completion gates with confirm-prompts, a full pre-archive sync assessment, post-sync re-verification of every delta capability, and hard stop conditions ('If the sync failed, or any capability does not match, report what differs and stop — do not archive') plus recovery handling ('ask again rather than archiving'). This matches anchor 5's explicit validation, error-recovery loops, and checklists. | 5 / 5 |
Progressive Disclosure | There are no bundle files (no references/, scripts/, or assets/), so all ~220 lines live in SKILL.md. The step structure itself is well organized, but the roughly 60-line delta-spec sync contract in step 4 (missing-main-spec branching, retire_capabilities rules, post-sync structural verification) is inline content that clearly belongs in a separate reference file. This matches anchor 3 — some structure, but content that should be separate is inline — rather than 4, where content would be appropriately placed across files. | 3 / 5 |
Total | 15 / 20 Passed |