Audit code comments (prompt)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/audit-code-comments-prompt/raw' -o ~/'.claude/skills/audit-code-comments-prompt/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/audit-code-comments-prompt/files/LICENSE.txt' -o ~/'.claude/skills/audit-code-comments-prompt/LICENSE.txt' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/audit-code-comments-prompt/files/NOTICE.txt' -o ~/'.claude/skills/audit-code-comments-prompt/NOTICE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/audit-code-comments-prompt/raw' -o '.cursor/skills/audit-code-comments-prompt/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/audit-code-comments-prompt/files/LICENSE.txt' -o '.cursor/skills/audit-code-comments-prompt/LICENSE.txt' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/audit-code-comments-prompt/files/NOTICE.txt' -o '.cursor/skills/audit-code-comments-prompt/NOTICE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/audit-code-comments-prompt/raw' -o '.agents/skills/audit-code-comments-prompt/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/audit-code-comments-prompt/files/LICENSE.txt' -o '.agents/skills/audit-code-comments-prompt/LICENSE.txt' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/audit-code-comments-prompt/files/NOTICE.txt' -o '.agents/skills/audit-code-comments-prompt/NOTICE.txt'

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

A wrong comment is worse than no comment. People trust it, and it sends them the wrong way. This prompt checks every comment against the code it sits on and says what to fix, rewrite or delete.

When to use

• You or an AI just wrote a lot of docstrings or comments and want them checked for accuracy.
• Old code is full of comments and you suspect many no longer match.
• Before a review, you want the comments added or changed in the diff checked.

When not to use

• You want a README or user guide written. Use write-readme-prompt.
• You want the code itself reviewed for bugs. Use review-code-prompt.
• You want messy code tidied, including comments. Use turn-messy-diff-into-clean-code-prompt.

Steps

1. Choose the scope: the comments changed in a diff, or a folder of older code.
2. Paste the prompt below into your AI coding tool. Change the base branch or swap in the folder.
3. Fix the critical issues first. A comment that states something false must change today.
4. Apply the removals you agree with. Delete comments that only restate the code.
5. Ask for rewrites of the rest one file at a time, and re-run the prompt on the result.

Prompt

Check the code comments and docstrings added or changed in this branch (git diff main...HEAD). Compare each one with the code it describes. Do not edit anything yet.

1. Accuracy: do parameters, return values, types and thrown errors match the signature? Does the described behaviour match the logic? Do referenced functions, files and flags still exist? Are claimed edge cases and performance notes true?
2. Completeness: are important assumptions, preconditions, side effects and error cases stated? Is the reason for a non-obvious choice explained?
3. Value: does it explain why, not just what? Flag comments that repeat the code, describe a temporary state, or will go stale with the next likely change.
4. Misleading parts: vague wording, old names from before a refactor, examples that no longer work, TODOs and FIXMEs that are already done.

Write for a new teammate reading this code a year from now.
Output:
- Critical: comments that are false or misleading (file:line, problem, fix).
- Improve: comments missing key context (file:line, what is missing, suggested wording).
- Remove: comments that add nothing (file:line, reason).
- Good examples worth copying, if any.
Give suggested wording for each rewrite. Wait for my go-ahead before changing files.

How to adapt

• Auditing old code instead of a diff? Replace the git command with "the comments in src/billing/".
• Have a doc style such as JSDoc, docstrings or rustdoc? Add "follow <style> for public functions".
• Public API or library? Ask for every exported function without a docstring to be listed too.
• Want it to apply the fixes? Reply "apply the critical and remove sections only".

Gotchas

• Some "obvious" comments are there for legal or licence reasons. Do not delete those headers.
• Comments that describe intended behaviour may reveal a code bug, not a comment bug. Check which is wrong.
• Comments can hold secrets or internal URLs. Remove any keys, passwords or private links you find.

Portability

Works with any language and any AI coding tool or chat AI. In a chat without repo access, paste the files with their comments.

Done when

• No comment states something the code does not do.
• Stale TODOs, old names and broken examples are fixed or removed.
• Remaining comments mostly explain why, and the code still builds and passes its tests.

Example prompt

"Check the comments and docstrings in my diff against the code. List the ones that are wrong, the ones missing context and the ones I should delete, with suggested wording."

---

Modified from the "comment-analyzer" agent in anthropics/claude-plugins-official (pr-review-toolkit, by Anthropic; README credits Daisy). Licensed Apache-2.0 per the LICENSE file at commit a7ba5b9. Original: https://github.com/anthropics/claude-plugins-official/blob/a7ba5b93db0c7c8d17f3f1d25853adca79598a1a/plugins/pr-review-toolkit/agents/comment-analyzer.md. Changes by TheSkillVault are listed in the metadata above and in NOTICE.txt. See LICENSE.txt.

Bundled files

• LICENSE.txt
• NOTICE.txt

Licence

Adapted from Anthropic (anthropics/claude-plugins-official, pr-review-toolkit, comment-analyzer; the plugin README credits Daisy, daisy@anthropic.com) (Anthropic (the upstream LICENSE keeps the blank Apache template line 'Copyright [yyyy] [name of copyright owner]'; no other copyright notice at this commit). Apache License 2.0 text in LICENSE.txt, attributions in NOTICE.txt), Apache License 2.0. Modified by TheSkillVault on 2026-11-04: the persona and the Claude Code invocation notes were removed; the five checks were rewritten as one copy-paste prompt with a fixed output, a why-over-what rule and an advisory-only default; added steps, adapt notes, gotchas and done-when. Not the original file.

Licence: Apache License 2.0. Attribution when you reuse it: Based on work by Anthropic (anthropics/claude-plugins-official, pr-review-toolkit, comment-analyzer; the plugin README credits Daisy, daisy@anthropic.com) (Anthropic (the upstream LICENSE keeps the blank Apache template line 'Copyright [yyyy] [name of copyright owner]'; no other copyright notice at this commit). Apache License 2.0 text in LICENSE.txt, attributions in NOTICE.txt, Apache License 2.0), https://github.com/anthropics/claude-plugins-official/blob/a7ba5b93db0c7c8d17f3f1d25853adca79598a1a/plugins/pr-review-toolkit/agents/comment-analyzer.md; adapted by TheSkillVault, https://theskillvault.ai