Content
63%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 dense, accurate rulebook with concrete syntax, named tests, and strong fail-closed validation guidance — highly actionable for a maintainer of this codebase. Its weaknesses are form, not substance: run-on paragraphs, repeated parallel clauses, and a per-field catalog inlined where a reference file would keep SKILL.md an overview.
Suggestions
Break the multi-clause paragraph walls (especially the 38-line opening of "What Gets Resolved") into short rule-per-bullet entries so each constraint is scannable.
Move the per-area field-resolution catalog (state, raw configs, params, sso_providers, portals, policies, cookies, token refresh, OAuth providers, documents) into a references/resolved-fields.md and keep SKILL.md as an overview with a summary table of supported areas.
Add one worked fixture example (a small <prefix>.Caddyfile + <prefix>.env + <prefix>_resolved.json triple) so the replacement pipeline is end-to-end executable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body carries no padding and no explanations of concepts Claude already knows — every sentence is a project-specific constraint — but it is ~300 lines with run-on paragraph walls (e.g., the 38-line paragraph in "What Gets Resolves") and repeated clauses ("resolve each value once" / "resolve once" / "resolve exactly once" reappear across the cookie, token-refresh, documents, and OAuth sections) that could be tightened. Matches anchor 3; not 2 because nothing is filler, not 4 because the prose needs restructuring rather than minor trims. | 3 / 5 |
Actionability | Concrete executable elements abound: caddyfile placeholder examples, the exact lookup syntax "secrets:<secret_id>:<key>", named fixture files ("<prefix>.env", "<prefix>_resolved.json"), named tests, and a specific pipeline ("Raw encoded directive fields usually need `cfgutil.DecodeArgs`, replacement of each argument, lossless encoding, and validation"). Not 5 because there is no worked end-to-end fixture example showing the transform from .Caddyfile/.env to resolved JSON. | 4 / 5 |
Workflow Clarity | "When adding a new placeholder-bearing field, check the authcrunch struct and validation path first" establishes a clear sequence (check struct → decode → replace → re-encode → validate → extend test coverage), and validation checkpoints with fail-closed semantics and named tests ("the old deployment still authorizes requests") are emphasized throughout. Not 5 because the full workflow is never assembled into one coherent ordered flow — the reader must piece it together from scattered sections. | 4 / 5 |
Progressive Disclosure | Section headers are clear and the cross-references to sibling skills are well signaled and one level deep (e.g., "See [persistent runtime state](../configuration-state/SKILL.md)"), but the skill has no bundle files of its own and ~200 lines of per-field resolution catalog are inlined in "What Gets Resolved" — exactly the material that belongs in a separate reference file. Matches anchor 3 (content that should be separate is inline); not 4 because the core detail is not split out of SKILL.md. | 3 / 5 |
Total | 14 / 20 Passed |