code-commenting
Guidelines for writing self-explanatory code with minimal comments. Covers when to comment (WHY not WHAT), anti-patterns to avoid, annotation tags, and public API documentation. Use when writing or reviewing code comments, docstrings, TODO/FIXME tags, code readability, or inline comments.
80
100%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a well-crafted skill description that clearly defines its scope around code commenting best practices. It effectively combines a concise 'what' statement with an explicit 'Use when' clause containing natural trigger terms. The description uses third person voice, avoids vague language, and carves out a distinct niche that would be easily distinguishable from other coding-related skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions and topics: writing self-explanatory code, when to comment (WHY not WHAT), anti-patterns to avoid, annotation tags, and public API documentation. These are concrete, actionable areas. | 3 / 3 |
Completeness | Clearly answers both 'what' (guidelines for self-explanatory code with minimal comments, covering WHY not WHAT, anti-patterns, annotation tags, API docs) and 'when' (explicit 'Use when' clause listing writing/reviewing code comments, docstrings, TODO/FIXME tags, code readability, inline comments). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'code comments', 'docstrings', 'TODO/FIXME tags', 'code readability', 'inline comments', 'reviewing code'. These cover common variations of how users would phrase requests about commenting practices. | 3 / 3 |
Distinctiveness Conflict Risk | Has a clear niche focused specifically on code commenting practices and documentation style. The triggers are specific enough (comments, docstrings, TODO/FIXME tags) that they wouldn't easily conflict with general coding skills or broader documentation skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
100%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is an exemplary skill file that is lean, well-structured, and immediately actionable. It uses tables for compact reference material, concrete code examples showing both anti-patterns and correct usage, and a final checklist for verification. The content respects Claude's intelligence by never explaining obvious concepts and focusing entirely on the specific guidelines and decision criteria.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every token earns its place. Uses tables for compact reference, code examples are minimal but illustrative, and no unnecessary explanation of concepts Claude already knows. The skill assumes competence and delivers only the delta knowledge needed. | 3 / 3 |
Actionability | Provides concrete, executable JavaScript examples showing both good and bad patterns. The decision table for when to comment vs. rename vs. add JSDoc is immediately actionable. The checklist at the end gives a clear verification mechanism. | 3 / 3 |
Workflow Clarity | This is a single-purpose instructional skill (commenting guidelines), not a multi-step destructive workflow. The decision table provides a clear sequence for determining what action to take, and the checklist serves as a validation checkpoint. For this type of skill, the clarity is excellent. | 3 / 3 |
Progressive Disclosure | For a skill under 50 lines with no need for external references, the content is well-organized into logical sections (when to comment, examples, JSDoc, tags, anti-patterns, checklist) that are easy to scan and navigate. No external files are needed given the scope. | 3 / 3 |
Total | 12 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- monkilabs/opencastle
- Commit
cc13aaf
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.