Content
88%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-crafted, project-specific scaffolding skill: dense imperative guidance, an explicit gated workflow with a real validation step (tsc) and pre-commit checklist, and effective use of existing repo files as templates. The two minor gaps are the non-copy-paste entry-point spec in 3b and the inlining of all per-file details in a single ~135-line file with no bundled references.
Suggestions
In section 3b, either include a minimal copy-paste entry-point template (imports, main() skeleton, fatal handler) inline or point to a bundled reference file containing one, so the entry point does not depend solely on adapting the enricher file.
Consider moving the detailed per-file instructions (3c-3f: config getter, docker-compose, package.json, env vars) into a references/ file (e.g. references/scaffold-details.md) and keep SKILL.md as the overview plus the workflow, reducing always-loaded tokens.
The workflow would benefit from a final verification step beyond tsc, such as running `docker compose config` (or equivalent) to validate the generated <name>.yaml before the pre-commit checklist.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes Claude's competence throughout: it states project-specific conventions (probe files, `qx.select` inline SQL, `requireEnv` fail-fast config) as imperatives without explaining pg-promise, tsx, docker-compose, or TypeScript concepts. Every line is either a requirement, a file path, a command, or a project convention — no padding. | 5 / 5 |
Actionability | Most guidance is executable: exact `cat` commands, exact package.json JSON ("start:<name>": "tsx src/bin/<name>.ts"), env var blocks, and a runnable check (`pnpm exec tsc -b services/apps/packages_worker`). The gap is section 3b — the entry point is a bullet spec of what to write (imports, `liveFilePath`, `main()` sequence, fatal handler) rather than copy-paste-ready code, leaning on Step 2's template read. Anchor 4 ('mostly executable, concrete code or commands with minor gaps') fits better than anchor 5. | 4 / 5 |
Workflow Clarity | The sequence is explicit and gated: requirements are gathered first ("Do not proceed until you have answers to 1-3"), canonical files are read before scaffolding ("Do not deviate from the patterns you see there"), and Step 4 provides a validation feedback loop ("Fix any errors before proceeding") followed by a pre-commit checklist and preflight. This matches anchor 5: clear sequence, explicit validation, error-recovery loop, and a checklist. | 5 / 5 |
Progressive Disclosure | The skill is a single well-organized file with clear step sections and a closing checklist, and it points to real in-repo canonical files (github-repos-enricher.ts, its yaml) as its detail source rather than duplicating them. However, at ~135 lines with all per-file scaffold instructions (3a-3f, ~60 lines of detail) inlined and no bundled references, there is a minor organization gap versus the cleanly split anchor-5 pattern. | 4 / 5 |
Total | 18 / 20 Passed |