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.
100
100%
Does it follow best practices?
Impact
Pending
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, lists specific topics covered, and includes an explicit 'Use when' clause with natural trigger terms. It uses proper third-person voice and is concise without being vague. The description effectively distinguishes itself from general coding or documentation 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 | Occupies a clear niche focused specifically on code commenting practices and documentation style. The specific triggers like 'TODO/FIXME tags', 'docstrings', and 'inline comments' are distinct enough to avoid conflicts with general coding or 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 — concise, well-structured, and highly actionable. It respects Claude's intelligence by never explaining obvious concepts, uses tables for rapid scanning, and provides concrete JavaScript examples that clearly illustrate the principles. The checklist at the end provides a useful validation mechanism for applying the guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely lean and efficient. Uses tables for quick scanning, no unnecessary explanations of what comments are or how JavaScript works. Every line earns its place. | 3 / 3 |
Actionability | Provides concrete, executable JavaScript examples showing both anti-patterns (✗) and correct patterns (✓). The JSDoc example is copy-paste ready, and the tables give specific, actionable guidance for each situation. | 3 / 3 |
Workflow Clarity | This is a single-purpose instructional skill (not a multi-step destructive process), and the decision workflow is crystal clear via the 'When to Comment' table — each situation maps to a specific action. The checklist at the end serves as a validation checkpoint for reviewing comments. | 3 / 3 |
Progressive Disclosure | For a skill under 50 lines with no need for external references, the content is excellently organized into logical sections (when to comment, examples, public APIs, tags, anti-patterns, checklist) with clear headers and tables for quick navigation. | 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
f5c8508
- 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.