comments-docs skill
✓ VerifiedEvaluates code comment quality and documentation practices using specific frameworks like the four comment types and the comments-first workflow.
- GitHub stars
- 18
- Files
- 2
- Last commit
- Oct 8, 2026
- License
- MIT
- Allowed tools
- 2
What does the comments-docs skill do?
comments-docs evaluates code comment quality and documentation practices using specific frameworks like the four comment types and the comments-first workflow.
Summary generated from the skill's SKILL.md.
About the comments-docs skill
Reviewing code documentation and comment quality is the primary function of this skill. It helps developers identify redundant comments that merely repeat the code, detect missing interface documentation, and recognize when complex comments signal underlying design flaws. An agent should load this tool when performing code reviews, designing new interfaces, or troubleshooting modules that are difficult to use despite existing documentation.
By using the Read and Grep tools, the skill analyzes specific files or modules to classify comments into four distinct types: interface, implementation, cross-module, and data structure member. It applies the comments-first workflow to evaluate if design intent was captured before implementation. The analysis produces actionable recommendations, such as deleting noise, adding precision to interface comments, or flagging leaky abstractions where comments become too convoluted to be useful.
What an agent can do with it
- 1Identify redundant documentationCheck if existing comments are simply rephrasing the code without adding new meaning.
- 2Detect design flaws through commentsDetermine if a complex or long comment is actually a signal that the code abstraction is poorly designed.
- 3Audit interface documentation qualityEnsure public interfaces provide both the mental model and specific technical details for callers.
- 4Evaluate documentation strategyAssess whether to use a comments-first workflow when building new software interfaces.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the comments-docs skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the comments-docs skill in Plugin
/plugin marketplace add codybrom/clairvoyance /plugin install clairvoyance@clairvoyance-plugins
Install the comments-docs skill in Claude Code
~/.claude/skills/comments-docs/SKILL.md
$ npx degit codybrom/clairvoyance/skills/comments-docs ~/.claude/skills/comments-docsInstall the comments-docs skill in Claude Code (project)
.claude/skills/comments-docs/SKILL.md
$ npx degit codybrom/clairvoyance/skills/comments-docs .claude/skills/comments-docsInstall the comments-docs skill in Codex
~/.agents/skills/comments-docs/SKILL.md
$ npx degit codybrom/clairvoyance/skills/comments-docs ~/.agents/skills/comments-docsInstall the comments-docs skill in Gemini CLI
~/.gemini/skills/comments-docs/SKILL.md
$ npx degit codybrom/clairvoyance/skills/comments-docs ~/.gemini/skills/comments-docsInstall the comments-docs skill in Claude.ai
npx degit codybrom/clairvoyance/skills/comments-docs comments-docs && zip -r comments-docs.zip comments-docs # claude.ai → Customize → Skills → + → Create skill → Upload a skill → comments-docs.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablecodybrom/clairvoyance/skills/comments-docs is public and reachablegithub.com/codybrom/clairvoyance/tree/HEAD/skills/comments-d ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-08github.com/codybrom/clairvoyance/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/codybrom/clairvoyance/blob/HEAD/skills/comments-d ↗Pass
- Pre-approved tools are scopedPre-approved: Read, Grepgithub.com/codybrom/clairvoyance/blob/HEAD/skills/comments-d ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 106 linesgithub.com/codybrom/clairvoyance/blob/HEAD/skills/comments-d ↗Pass
SKILL.md
View on GitHubComments & Documentation Review Lens
When invoked with $ARGUMENTS, focus the analysis on the specified file or module. Read the target code first, then apply the checks below.
Comments are not recording a design that already exists. They are the medium in which the design is discovered. Code captures mechanism. Comments capture meaning. Even a perfect programming language could not replace them. The information types are distinct.
When to Apply
- Reviewing code with comments (or conspicuously lacking them)
- When writing new interfaces and considering documentation strategy
- When comments feel useless or redundant
- When a module is hard to use despite having documentation
Core Principles
The Guiding Principle
"Comments should describe things that aren't obvious from the code." — John Ousterhout, A Philosophy of Software Design
"Obvious" is from the perspective of someone reading the code for the first time, not the author. If a reviewer says something isn't obvious, it isn't. Don't argue, clarify.
Four Comment Types
1. Interface Comments
What and why for callers. Must be sufficient to use the interface without reading implementation. Operate at two levels: intuition (a sentence giving the mental model) and precision (argument/return docs more specific than the code). A comment that says "offset" does not specify inclusive vs exclusive.
2. Implementation Comments
What a block does (high-level) and why, not line-by-line how. For variable comments, think nouns, not verbs: describe what the variable represents, not how it's manipulated.
3. Cross-Module Comments
Document dependencies spanning module boundaries. Place at a convergence point, or maintain a central designNotes file with labeled sections per topic and short pointer comments in the code (// See "Zombies" in designNotes). Neither approach is perfect. This is a genuinely unsolved problem.
4. Data Structure Member Comments
Each field should have a comment capturing what's not obvious from the type or name: what it represents, units, valid ranges, boundary conditions (inclusive/exclusive), nullability, resource ownership (who frees/closes), invariants and relationships to other fields.
"Comment Repeats Code" Test
Useful comments say things the code does not. If another developer could write the same comment just by reading the surrounding code, it doesn't need to exist and should be deleted.
Rephrasing an entity name doesn't cut it. A comment about fetchUserProfile that says "Fetches the user profile" is still noise.
Hard-to-Describe Signal
When a comment must be long, qualified, or convoluted, that's a design problem, not a writing problem. Simple descriptions come from well-designed abstractions.
| Comment | Implementation | Signal |
|---|---|---|
| Short, simple | Substantial | Deep — hides complexity well |
| Long, complicated | Short | Shallow — description nearly as complex as code |
| Must describe internals | Any | Leaky abstraction |
Comments-First Workflow
Write interface comments before method bodies. If a comment is hard to write, the abstraction is wrong, and you find out before writing the implementation. Comments written after-the-fact produce worse results: design intent has scrolled out of the context window, and a finished implementation contaminates your perspective, so you end up restating the code instead of capturing why you wrote it.
- Class interface comment: purpose and abstraction, before anything else
- Public method comments + signatures: bodies empty. Iterate until structure feels right
- Instance variable declarations + comments: once interface stabilized
- Fill in method bodies: implementation comments as needed. Comments are already done
See the full workflow for the complexity canary tests and cost analysis.
The Four Excuses
- "Good code is self-documenting." A signature gives you types and parameter names. It does not tell you when to call the method, what the return value means, or why the method exists. That information lives in comments. When readers must study an implementation to use it, a module offers no real abstraction.
- "I don't have time." Comments are a small fraction of total output — well under 10% of the tokens spent on a task. Reframed: "I don't have time to design."
- "Comments get out of date." Manageable with discipline at the point of change and code review.
- "All comments I've seen are worthless." Solvable with technique, not intention.
Why "Comments Are Failures" Is Wrong
Robert Martin argues in Clean Code that comments are failures and signs that the code wasn't expressive enough. His alternative is method extraction: replace a commented block with a well-named method.
Method names work for simple operations. extractSubstring is better than a comment above a five-line block. But names can hit a ceiling. A name can say what a method does but it won't say why, describe the preconditions or explain non-obvious constraints. A name alone cannot carry that, but a comment can. Taken to the extreme, method extraction encourages splitting code into infinite small methods, which can increase complexity rather than reduce it.
The issue is a default bias, not a hard rule: treating comments as "junk" causes them to be skipped, and useful design context goes unrecorded for every collaborator — human or agent — who reads the code later. The best place for design context is right next to the code it describes, not in a separate document that the reader may never find or even know to look for.
Review Process
- Classify existing comments: Interface, implementation, cross-module, or data structure member?
- Check for repeats-code: Same words as the entity name?
- Check for missing interface comments: All public interfaces documented? Both intuition and precision?
- Evaluate hard-to-describe: Long or convoluted comments? Investigate the design.
- Check cross-module docs: Dependencies documented? Canonical location?
- Check for comment rot: Does each comment's claims still match the code and behavior it describes? Flag mismatches.
- Recommend: Delete noise, add missing interface comments, flag hard-to-describe as design problems
Red flag signals for comments are cataloged in red-flags (Comment Repeats Code, Implementation Documentation Contaminates Interface, Hard to Describe).
References
For deeper coverage, load on demand:
- Comments-first workflow: Full 6-step process, complexity canary tests, cost analysis, and why after-the-fact comments are a red flag.
Files in this skill
2comments-docs skill questions
How do I install the comments-docs skill in Claude Code?
Run npx degit codybrom/clairvoyance/skills/comments-docs ~/.claude/skills/comments-docs. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the comments-docs skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How can I tell if a comment is redundant?
Use the 'Comment Repeats Code' test: if a developer could write the same comment just by reading the surrounding code, it should be deleted.
What does a long or complicated comment signal about the code?
A long or convoluted comment is often a signal of a design problem rather than a writing problem, indicating a shallow abstraction.
What is the comments-first workflow?
It is a process where you write interface comments before method bodies to ensure the abstraction is correct before implementation begins.