Content
67%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 well-structured and actionable for setup, discovery, and workflow selection, with executable bash snippets and a strong success-criteria checklist. Its two real weaknesses are redundancy (the Rationalizations section and triple-stated database-selection logic repeat earlier content) and the fact that the three core workflow files it delegates to are missing from the bundle.
Suggestions
Create the missing workflows/build-database.md, workflows/create-data-extensions.md, and workflows/run-analysis.md (or fix the references) — the skill's core execution steps currently point to files that do not exist in the bundle.
Consolidate "Essential Principles" and "Rationalizations to Reject" into a single section: the rationalizations restate the principles point-for-point and could be folded in as brief "reject this shortcut" notes, cutting substantial token cost.
Merge the database-selection guidance that currently appears in Database Discovery, Auto-Detection Logic, and Database Selection Prompt into one canonical section with the discovery command, metadata loop, and AskUserQuestion template.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is operational rather than tutorial-style (no explanations of concepts Claude already knows), but it is noticeably duplicated: "Rationalizations to Reject" restates nearly every "Essential Principle" point-for-point (database quality, zero findings, build-mode=none, data extensions, suite filtering), and database-selection guidance appears in three separate sections (Database Discovery, Auto-Detection Logic, Database Selection Prompt). This fits "mostly efficient but includes some unnecessary explanation or could be tightened" better than the noticeably-padded anchor 2, but a tightened version could cut substantial length. | 3 / 5 |
Actionability | Guidance in the body is executable and copy-paste ready — the output-directory resolution loop, the `find . -maxdepth 3 -name "codeql-database.yml"` discovery command, the per-database metadata extraction loop, and the version check — plus concrete decision tables and AskUserQuestion option blocks. It is not a 5 because the core pipeline steps ("build database → create data extensions → run analysis using the workflows below") delegate to workflows/build-database.md, workflows/create-data-extensions.md, and workflows/run-analysis.md, none of which exist in the bundle, leaving the actual analysis commands unspecified. | 4 / 5 |
Workflow Clarity | The three workflows are laid out in a selection table with explicit gating ("execute it step by step without skipping phases. Each phase gates the next"), auto-detection is a condition/action table, and a Success Criteria checklist provides end-state validation including zero-finding investigation. Minor validation gaps remain — per-phase checkpoints and error-recovery loops are promised inside the three missing workflow files, so they cannot be verified here — which keeps it below the anchor-5 explicit-validation example. | 4 / 5 |
Progressive Disclosure | Structure is good: a clear Reference Index table signals all 12 references/*.md files (all of which exist) with one-line content descriptions, links are one level deep, and overview-level content stays in SKILL.md. This is more than anchor 3 (references are clearly signaled, not buried) but short of anchor 5 because the organization gap is not minor: the three workflow files central to execution — workflows/build-database.md, workflows/create-data-extensions.md, workflows/run-analysis.md — are referenced in the Workflow Selection table, Reference Index, and body text but do not exist in the bundle. | 4 / 5 |
Total | 15 / 20 Passed |