Content
90%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 tight, information-dense contract document: every line carries non-obvious rules (dry-run defaults, cooldowns, refusal conditions, exit codes, checkout constraints) with no padding, and the script invocations are fully specified down to flags and KEY formats. The main gaps are the implicit end-to-end script ordering and references to lib/ files that are missing from the presented bundle.
Suggestions
State the script run order explicitly (e.g., 'Run findings-doctor first, then findings-match before investigating, then findings-upsert to file') so the orchestration sequence does not have to be inferred from section order.
Include or verify the lib/ files (lib/cli.ts, lib/plan-format.ts, lib/artifacts.ts, lib/findings.ts) in the skill bundle — the Library section references them but they are absent, so readers cannot resolve them.
Add one fully-instantiated example invocation with literal values (e.g., a sample --plan path and run id) to anchor the placeholder-based command templates.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every line states repo-specific contract rules Claude could not infer ("It is a dry run without --apply, and re-runs finish what a partial failure skipped"; "Exit code 2 means the tracker could not be reached or rejected the credentials. Never treat it as a pass."; the blobless-clone git constraints), with zero concept explanations or padding. Anchor 4 ('minor instances of over-explanation') does not fit — nothing here can be trimmed without losing a real rule. | 5 / 5 |
Actionability | Gives the exact runner ("F=.agents/skills/fragility-common/scripts; pnpm exec tsx $F/<script>.ts [...]") plus every flag for each script's common cases (--run, --systems, --files, --plan, --key, --distinct-from, --system, --source, --source-title, --note, --apply, --over-cap, --run-url) along with KEY formats and env var. Not 4: there is no pseudocode or missing step — the commands are fully executable once parameter values are supplied, which is inherent to CLI parameter docs. | 5 / 5 |
Workflow Clarity | Validation and recovery are strong (findings-doctor as a credential pre-check, dry-run default, "re-runs finish what a partial failure skipped", explicit exit-code-2 handling), so the batch-operation cap does not apply. But the end-to-end script order (doctor → match → upsert) is only implied — the sole explicit sequencing statement is "Run it before investigating", which keeps it below anchor 5's 'clear sequence with explicit validation steps'. | 4 / 5 |
Progressive Disclosure | Well-sectioned overview with one-level-deep references: the three scripts named under '## Findings tracker' all exist in scripts/, and the Library section maps each file to its role. However, the referenced lib/cli.ts, lib/plan-format.ts, lib/artifacts.ts, and lib/findings.ts are absent from the bundle, so those references do not resolve — a minor organization gap that fits anchor 4 rather than 5. | 4 / 5 |
Total | 18 / 20 Passed |