Content
81%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 dense, highly actionable skill body with excellent executable command coverage and a well-sequenced multi-mode workflow with explicit validation and recovery paths. Its main weaknesses are meta-framework padding (SSL primitive table, Scenes scaffolding, duplicated fallback description) that inflates token cost, and an over-long body that inlines spec detail while referencing bundle files that are not actually shipped.
Suggestions
Remove or compress the framework meta sections ("Actions | SSL primitive | Evidence" table, "Scenes" scaffolding, "Intent signature", "Control-flow features") into a short mode-dispatch description, cutting roughly 40 lines without losing executable guidance.
Deduplicate the OpenAlex/Semantic Scholar fallback story: keep the detailed "Provider Fallback" section and reduce the Transitions/Dependencies mentions to one-line pointers.
Ship or trim the references: either include the referenced "resources/*.md" and "../_shared/*" files in the bundle, or cut the 18-item guardrails down to the load-bearing ones and defer exact enum/format rules to "resources/sidecar-spec.md".
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly operational, but padded with framework meta-description that does not instruct: the "Actions | SSL primitive" table (SELECT/READ/INFER), the Scenes scaffolding (PREPARE/ACQUIRE/REASON/ACT/VERIFY/FINALIZE), "Intent signature", and "Control-flow features". The OpenAlex fallback is also described twice (Transitions and the Provider Fallback section). Below anchor 4 because these sections are trimmable without losing guidance; above anchor 2 because the bulk is concrete commands and rules, not concept explanation Claude already knows. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready commands cover the common cases: "oma scholar search \"diffusion super resolution\"", "oma scholar get --section statements \"knows:generated/reconvla/1.0.0\"", "oma scholar lint --fail-on-warning paper.knows.yaml", raw curl endpoints, and a troubleshooting table keyed to exact error strings with concrete fixes ("value: '22' -> value: 22"). | 5 / 5 |
Workflow Clarity | Entry -> Scenes -> Transitions -> Failure and recovery -> Exit is clearly sequenced with explicit validation checkpoints (VERIFY scene, "run lint before sharing", guardrail 13) and feedback loops for error recovery (retry or OpenAlex fallback on API timeout, fix-indentation loop on YAML parse failure, error-to-fix troubleshooting table). No destructive or batch operations lack validation. | 5 / 5 |
Progressive Disclosure | A dedicated References section lists one-level-deep, well-signaled files ("resources/sidecar-spec.md", "resources/api-endpoints.md", etc.) and heavy spec detail is nominally deferred. Below anchor 5 because the ~275-line body still inlines content that belongs in those files (the 18-item guardrails largely duplicate "resources/sidecar-spec.md"), and none of the referenced files ("resources/*.md", "../_shared/*", "../../rules/i18n-guide.md") are present in the shipped bundle, so reference targets cannot be verified. Above anchor 3 because splitting intent and navigation are otherwise clear. | 4 / 5 |
Total | 17 / 20 Passed |