Content
77%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 delivers highly concrete, actionable guidance with a clearly sequenced workflow and explicit fallback handling for every failure mode, plus worked examples and complete output templates. Its weaknesses are redundancy (the advisory-only rule and escalation rule are each stated multiple times) and a monolithic 430-line single file whose templates and optional obsidian integration belong in reference files.
Suggestions
State the advisory-only rule once (e.g. in Purpose) and remove the repetitions in Design Principles, the step-6 output template, and Anti-Patterns; likewise keep the two-consecutive-runs escalation rule in one place instead of both the template and its own section.
Move the verbose output template, the clean-run template, and the obsidian Agent Memory follow-up (with its PowerShell commands) into a references/ file (e.g. templates.md), keeping SKILL.md as a lean overview with one-level-deep, clearly signaled references.
Tighten section 2.5's five drift-sign bullets and the six reflect prompts by merging overlapping items, and fix the inconsistent indentation in the step-6 template (e.g. 'Evidence:' and 'Workaround used:' lines) so the format is unambiguous when copied.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Quotes: 'This skill does not modify SKILL.md files automatically', 'Advisory — produces recommendations, never edits SKILL.md directly', 'No SKILL.md changes made — recommendations are advisory', '❌ Auto-editing the calling skill's SKILL.md — always advisory'. The advisory-only rule is stated four times, and the two-consecutive-runs escalation rule appears both inside the step-6 output template ('Self-improvement rule: If the same friction point appears in two consecutive runs, escalate to P0') and again as its own '## Escalation Rule' section. The content is otherwise directive rather than explanatory, so it is mostly efficient but could be tightened — the level-3 anchor — rather than noticeably padded. | 3 / 5 |
Actionability | Quotes: the exact invocation shape ('Run skill-reflection for <skill-name>. SKILL.md path: ... Steps completed: ... Friction: ...'), two fully worked examples (azure-local-deploy, branch-wrapup), the structured input table, the seven-category friction taxonomy, complete output templates for both friction and clean runs, the priority definitions table, and the executable command 'python .github/skills/obsidian/scripts/obsidian.py search ... --format json'. Guidance is copy-paste ready and covers the common cases (missing path, missing step list, unavailable history, no friction), matching the fully-executable anchor; the only minor gap is that step 5's history search does not name the search mechanism, but step 7 supplies one. | 5 / 5 |
Workflow Clarity | Quotes: 'When invoked, follow these steps in order' with numbered steps 1-8; explicit fallback loops such as 'If the caller provides the skill name but no step list, ask only for the missing steps and statuses', 'If SKILL.md path is missing ... continue with the rest of the reflection instead of blocking the run', 'If those history sources are unavailable, say so explicitly instead of assuming there is no repeat friction', and a dedicated clean-run branch ('When There's No Friction'). The sequence is clear with explicit validation/checkpoint behavior for each failure mode, and since the skill is advisory (non-destructive, non-batch) the validation cap does not apply. | 5 / 5 |
Progressive Disclosure | The body is a single ~430-line file with no bundle files (no references/, scripts/, or assets/ exist) and no external references at all. Sections are well-organized with headers, but content that would fit better in separate reference files is inlined — the ~45-line verbose output template, the clean-run template, and the obsidian Agent Memory follow-up with its PowerShell commands — matching the anchor for content that should be separate being inline rather than the good-placement anchor. | 3 / 5 |
Total | 16 / 20 Passed |