Explain code intent and non-obvious decisions in comments.
npx skills add https://github.com/obra/clank --skill commenting-intent-obra
Please help me install this Agent Skill. Skill: Commenting Intent Source: https://github.com/obra/clank/tree/main/skills/coding/commenting-intent Command: npx skills add https://github.com/obra/clank --skill commenting-intent-obra
This Skill eliminates over-commenting and unhelpful comments that just restate code mechanics, ensuring your comments provide genuine value by explaining intent, decisions, and non-obvious reasoning.
Use the Commenting Intent skill to review this code and suggest where to add comments explaining the reasoning behind implementation choices.
High-intent search queries and answers about installing and using this skill.
Intent-focused comments explain why code exists and the reasoning behind design choices rather than describing mechanics. Document non-obvious decisions, trade-offs, and the business logic that justifies the implementation, helping future maintainers understand the original reasoning.
Comment on why you selected a specific algorithm over alternatives, the trade-offs involved, and non-obvious implementation choices. Explain constraints, performance considerations, or business rules that drove the decision rather than restating the algorithm's steps.
Add comments explaining the origin and purpose of magic numbers—capture the business rule, formula derivation, or constraint they represent. This preserves context for maintainers and prevents future developers from changing values without understanding their significance.
Mechanistic comments duplicate what the code already shows and become stale as code evolves. Comments explaining intent, decisions, and reasoning remain valuable guides for maintaining, debugging, and extending code across different contexts and team members.
Yes, intent-focused commenting applies across all languages. The principle—capture why code exists, not what it does—remains constant whether you're writing Python, Java, JavaScript, or any other language, ensuring consistent documentation standards.
CarGDevReview pull requests for security, logic, performance, and style issues.
hatlesswizardAudit code identifiers for naming quality issues per Clean Code Ch2.
wyattowalshEstimate algorithmic complexity and parse profiler outputs to identify hotspots.
seb1nGenerate API references, docstrings, and README files for codebases.
