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 instruction skill: goal-branched workflow, concrete MCP tool guidance with defaults and tradeoffs, important domain gotchas ("launched" vs "recently deployed", weight scaling, dormant permanent flags), and clean one-level progressive disclosure into two real reference files. Main improvement room is adding example tool invocations and trimming a few narrative asides.
Suggestions
Add one or two example MCP tool invocations with actual arguments (e.g., a representative `list-flags` or `find-stale-flags` call) so the call shape is unambiguous.
Trim the meta opening sentence and narrative asides (e.g., "tells a different story than one inactive everywhere") to save tokens without losing guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with tables, tool names, and parameter defaults, and never explains concepts Claude already knows (no "what is a feature flag" padding). A few tokens could still be trimmed — the meta opener "You're using a skill that will guide you through auditing..." and the narrative aside "tells a different story than one inactive everywhere" — which places it at 4 rather than 5. | 4 / 5 |
Actionability | Gives concrete executable guidance: `list-flags` with `state`/`type` filters, `find-stale-flags` with `inactiveDays` (default 30, with 60/90 vs 7/14 tradeoff guidance), `includeOnly` values, and the weight-scaling gotcha ("A weight of `60000` means 60%"). Falls short of 5 because no example MCP tool invocations with actual arguments are shown, leaving minor ambiguity in call shape. | 4 / 5 |
Workflow Clarity | Six clearly sequenced steps branch by user goal with explicit checkpoints (confirm `projectKey`, "Don't recommend action without more context", safe/caution/blocked verdicts, and a categorization scheme ordered by confidence). Not 5 because error-recovery/feedback loops are not made explicit; comfortably above 3 since checkpoints are present and concrete. | 4 / 5 |
Progressive Disclosure | SKILL.md is a true overview (~110 lines) and both referenced files (`references/flag-health-signals.md`, `references/removal-readiness-checklist.md`) exist with substantive content, are one level deep, clearly signaled in the body ("See [Flag Health Signals](references/flag-health-signals.md) for the full interpretation guide") and indexed in a References section. Exact match for the 5 anchor. | 5 / 5 |
Total | 17 / 20 Passed |