Content
53%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 a deliberately thin Pi-host wrapper that delegates the real workflow to an external file, with strong fail-closed dispatch semantics and clear flag-handling rules. Its main weaknesses are redundant flag-handling instructions repeated across the objective and context sections, and the fact that the single workflow reference is an unresolved placeholder path, so the skill body alone cannot drive execution.
Suggestions
Consolidate the flag rules: state the active/inactive derivation and --force precedence once (either in <objective> or <context>) instead of repeating them across three bullet groups.
Inline a minimal execution skeleton (phase order, the 9 doc types, what preservation_check and wave execution mean) so the skill degrades gracefully if the external workflow file fails to resolve, and so the batch/destructive flow has visible validation checkpoints.
Replace or supplement the "__GSD_PI_ENGINE_ROOT__" placeholder with a resolvable path (or copy the workflow into references/) so the one-level-deep reference is followable within the installed skill bundle.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The Pi-dispatch and Pi-includes sections are tight and necessary, but the flag-inactivity rules are stated three times: the objective's six-bullet "Flag handling rule", the context's two flag bullets, and the context's "Do not infer that a flag is active just because it is documented in this prompt" bullets. Mostly efficient, but the duplicated flag semantics should be consolidated into one section. | 3 / 5 |
Actionability | Dispatch guidance is concrete and executable (call gsd_dispatch with role and task, fail-closed on unresolved role or child failure, --force/--verify-only precedence), but the core execution workflow lives entirely in the external "@__GSD_PI_ENGINE_ROOT__/gsd-core/workflows/docs-update.md" reference, so the body itself is missing the specific steps (doc types, wave execution, preservation prompts) needed to execute. Some concrete guidance, incomplete on its own. | 3 / 5 |
Workflow Clarity | The body sequences only two steps (read execution_context files, then follow the workflow) and names the gates to preserve ("preservation_check, flag handling, wave execution, monorepo dispatch, commit, reporting") without defining or ordering them; validation checkpoints are delegated to the external file. The skill is a batch, partially destructive operation (up to 9 docs, --force overwrites, commit), which caps workflow clarity at 3. | 3 / 5 |
Progressive Disclosure | The body is a well-organized thin overview with clearly labeled sections (objective, execution_context, context, process) and a single, clearly signaled, one-level-deep reference under <execution_context>. It falls short of 5 because that reference is a "__GSD_PI_ENGINE_ROOT__" template placeholder that does not resolve to a real file within this skill bundle (no references/ directory exists), leaving navigation dependent on install-time substitution. | 4 / 5 |
Total | 13 / 20 Passed |