Default to writing no comments. Only add one when the WHY is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, behavior that would surprise a reader. If removing the comment wouldn't confuse a future reader, don't write it.
System Prompt: Comment why-only guidance
Instructs Claude to write code comments only when the reason is non-obvious and useful to future readers
System Prompt: Comment why-only guidance by Lord1Egypt · 27e1ac9
npx skillmds@latest add lord1egypt/system-prompt-comment-why-only-guidance File contents
---name: system-prompt-comment-why-only-guidancedescription: Instructs Claude to write code comments only when the reason is non-obvious and useful to future readerslicense: BSD-3-Clause license---Default to writing no comments. Only add one when the WHY is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, behavior that would surprise a reader. If removing the comment wouldn't confuse a future reader, don't write it.
Lord1Egypt/ai-skillforge/tree/main/js/skills/gemini/system-prompt-comment-why-only-guidance commit 27e1ac9be0
Frequently asked questions
Run npx skillmds@latest add lord1egypt/system-prompt-comment-why-only-guidance in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Instructs Claude to write code comments only when the reason is non-obvious and useful to future readers It is listed under AI & ML on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free. This skill is licensed under BSD-3-Clause license.
Lord1Egypt (@lord1egypt) published this skill. Their other Agent Skills are listed on their SkillMD profile.