Code Comments

This is the antidote to documentation that lives in a wiki somewhere and rots while the code evolves. It teaches Claude to write comments that explain *why* code exists, not what it does, across four levels: file headers that show how pieces fit together, function docs that describe contracts and edge cases, inline comments for non-obvious decisions, and architectural notes for big tradeoffs. The philosophy is simple: write for future you, your teammates, and AI assistants who only see one file at a time. Includes language-specific patterns for TypeScript, Swift, Python, and React. Best for teams who've learned the hard way that separate documentation drifts but comments next to code get updated together.

install copies · 90 days. Times the install command was copied on this site in the last 90 days, bots filtered.: 21
skills.sh installs: 629
GitHub stars: 49
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add petekp/claude-code-setup --skill code-comments --agent claude-code

Installs into .claude/skills of the current project.

Files

Code comments

Delete every comment that is not on the keep list. When you are not sure a comment fits an item, delete it. A comment that explains our own code usually means the code should change: make the code say it, then delete the comment. Before adding a comment while writing code, hold it to the same list.