Content
86%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-engineered skill body: lean overview text with concrete commands, a reasoned decision framework (surface → engine → placement), hard rules that encode real pitfalls, and exemplary one-level-deep reference structure with a Read/When navigation table. The remaining gaps are minor — kernel-connection code is described rather than shown, and error-recovery loops are delegated to references rather than stated.
Suggestions
Inline a 3-4 line copy-paste example of the resident-kernel connection path (dynamic-import of @duckdb/node-api and the sys.path.insert pattern for the Python lane) so the core execution loop is fully executable from SKILL.md alone.
Add a short failure-then-retry loop for the fragile steps — e.g., when DuckDB spills past its memory cap or an ensure-deps install fails, show the escalation to the uv lane rather than only describing it.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and lean with zero concept padding — no 'what is DuckDB' filler — and every explanatory passage earns its tokens with non-obvious operational judgment (e.g., 'each one-shot process pays roughly a second of spawn-plus-import overhead', 'Performance folklore... measure on the actual data'). It matches the 'lean and efficient; every token earns its place' anchor rather than score 4, whose minor over-explanation is absent here. | 5 / 5 |
Actionability | Concrete, runnable commands appear throughout — 'scripts/ensure-js-deps.sh', 'uv run --with ...', 'CREATE TABLE t AS SELECT ...', "FROM 'data.csv'", '.pl() via Arrow', and the 'uv run scripts/quick-query.py <file> [SQL]' CLI with flags — but the kernel-connection steps are described rather than shown ('Dynamic-import it, connect once', 'sys.path.insert the printed directory'), leaving minor gaps. This is 'mostly executable guidance... with minor gaps', not score 5's copy-paste-ready coverage. | 4 / 5 |
Workflow Clarity | A clear decision sequence exists — surface selection (kernel → uv lane → one-shot), 'Probe before you compute' pre-flight check, then placement (load / stream / remote) — with a verification-minded output contract ('report row counts and timing') and a mandated visual QA step for charts. It sits at 'clear sequence with most checkpoints present; minor validation gaps' rather than 5, since there are no explicit error-recovery/feedback loops (e.g., what to do when a query spills or a dep install fails beyond the uv-setup reference). | 4 / 5 |
Progressive Disclosure | The ~100-line overview splits cleanly into five real one-level-deep reference files, each surfaced twice with clear signals: inline 'read references/X.md before Y' cues plus a 'Read | When' table mapping every reference to its trigger condition. All five referenced files exist, none reference further reference files, and per-surface detail (surfaces, Polars API, sizing, charting, uv repair) is appropriately out-of-line — matching the 'clear overview with well-signaled one-level-deep references' anchor. | 5 / 5 |
Total | 18 / 20 Passed |