Content
62%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 content is well organized with an exemplary validated remediation workflow and concrete commands, but as a standalone skill bundle it is incomplete: the scanner script and the referenced references/remediation.md are missing, and promotional/duplicated material inflates the token cost. Fixing the dangling reference and trimming the marketing content would raise both actionability and conciseness.
Suggestions
Bundle the actual secret_scan.py script (and the Claude Code hook / pre-commit templates) in scripts/ so the documented commands are executable, or inline minimal install instructions for obtaining them.
Ship references/remediation.md with the exact git filter-repo --replace-text mirror-clone commands promised in remediation step 3, or inline those commands in the Example section.
Remove the promotional duplication — the footer catalog link, the repeated 'Built by Nex AI' lines, and the FAQ question that restates Known limitations — to tighten token efficiency.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core material (command menu, remediation steps, limitations) is efficient and assumes competence, but there is real padding a skill should not carry: promotional lines appear three times ("Free skill by Nex AI", "Built by Nex AI, nex-ai.be", the footer advertising the paid catalog), and the first FAQ answer ("Does it check whether a key is live? No...") restates the Known limitations section almost verbatim. This sits between the 3 anchor (mostly efficient, some unnecessary sections) and the 2 anchor (several padded sections), but the bulk remains useful, so 3 fits best. | 3 / 5 |
Actionability | Concrete, copy-pasteable commands are present ("secret_scan.py --staged", "--diff origin/main", "--history", "--stdin", "install-hook", plus a specific remediation sequence with os.environ replacements), but key execution details are missing from the bundle: the skill states "Scripts, extension source, and templates from the original package are not in this folder", so secret_scan.py itself is absent, and step 3 defers the exact history-rewrite commands to "references/remediation.md", a file that does not exist in this folder. This matches the 3 anchor (some concrete guidance but incomplete, missing key details) rather than 4, whose minor gaps would not include the tool itself. | 3 / 5 |
Workflow Clarity | The remediation workflow is a model of sequencing and validation: "Do this, in this order" gives five numbered steps — rotate first ("Removing them from git does not make them safe"), move values to environment, rewrite history, "**Re-scan**: secret_scan.py --history must come back clean", then install the guard hook. The re-scan requirement is an explicit validation checkpoint with an implied fix-and-retry loop for a destructive operation (history rewrite), so the destructive-operation cap does not apply and the content matches the 5 anchor. | 5 / 5 |
Progressive Disclosure | Section structure is clear (What it does / Rules / Guard rails / When to use / Known limitations / Example / Questions) and the body stays a reasonable length, but the one reference it makes — "exact commands are in references/remediation.md" — points to a file that is not in the bundle (no references/, scripts/, or assets/ directories exist), and the referenced script is likewise absent. This lands at the 3 anchor: decent organization, but a reference that is signaled yet broken and detail that is neither inline nor available elsewhere keeps it below 4. | 3 / 5 |
Total | 14 / 20 Passed |