Content
78%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-structured tool-dispatch skill: concrete tool names, parameters, defaults, and troubleshooting guidance organized into a clear workflow, with heavy detail correctly offloaded to a single real reference file. The main improvement opportunities are removing the thrice-stated search-before-reading rationale and adding one complete example tool invocation inline.
Suggestions
State the 'search before reading' principle once (in the intro) and cut its repetition in sections 1 and 3, including section 3's re-explanation of what a search call returns.
Add one complete example invocation (e.g. a sample codebase_search call with a query, fileFilter, and minScore) so the inline guidance is copy-paste ready without opening the reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is largely lean and directive, but the 'search before reading / never read a file just to find out if it's relevant' rationale is repeated in the intro, section 1, and section 3, and section 3 re-explains what a search call returns. These small redundancies could be trimmed. | 4 / 5 |
Actionability | Highly concrete for an instruction-only skill: specific tool names, parameters (fileFilter, languageFilter, minScore default 0.10), example queries ('how is authentication handled'), env-var modes, and a goal-to-tool table. No complete example invocation appears inline (deferred to the reference file), which is a minor gap. | 4 / 5 |
Workflow Clarity | Six clearly numbered steps in a coherent order, with a dedicated troubleshooting section providing error-recovery guidance ('If search returns no results, the project may not be indexed', stale results -> codebase_update). Validation is handled as a conditional section rather than integrated checkpoints in the main flow. No destructive or batch operations, so no cap applies. | 4 / 5 |
Progressive Disclosure | The body is a well-organized overview (workflow sections plus a goal-to-tool quick-reference table), with bulk parameter detail appropriately split into a single, clearly signaled, one-level-deep reference — references/tool-reference.md, which exists as a real file — matching the ideal structure. | 5 / 5 |
Total | 17 / 20 Passed |