Commenting Intent
Comment WHY code exists and non-obvious decisions, not WHAT code does (mechanics)
Install
npx skills add obra/clank --skill Commenting Intentgit clone --depth 1 https://github.com/obra/clank.git /tmp/clank
mkdir -p ~/.claude/skills
cp -r /tmp/clank/skills/coding/commenting-intent ~/.claude/skills/Commenting-IntentPersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# Commenting Intent
## Overview
Good comments explain WHY, not WHAT. Code already shows what it does. Comments should explain intent, decisions, and non-obvious reasoning.
**Core principle:** If the comment just restates the code, delete the comment or improve the code.
## Baseline Violation
**Agents comment mechanics (what code does):**
❌ **Over-commenting (baseline):**
```python
# Calculate subtotal by multiplying price and quantity for each item, then summing
subtotal = sum(item.price * item.quantity for item in items)
# Calculate tax amount based on the subtotal and tax rate
tax = subtotal * tax_rate
# Calculate final total by adding subtotal and tax
total = subtotal + tax
```
**Problem:** Comments just restate obvious code. No value added.
✅ **Comment intent only:**
```python
def calculate_total_price(items, tax_rate):
"""Calculate order total including tax."""
subtotal = sum(item.price * item.quantity for item in items)
tax = subtotal * tax_rate
return subtotal + tax # No comments needed - code is clear
```
## What to Comment
### 1. Non-Obvious Decisions
✅ **WHY you chose this approach:**Details
- Skill name
Commenting Intent- Repository
- obra/clank
- Path
skills/coding/commenting-intent/SKILL.md- Repo updated
- 9 October 2025
FAQ
What does the Commenting Intent skill do?
Comment WHY code exists and non-obvious decisions, not WHAT code does (mechanics)
How do I install the Commenting Intent skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add obra/clank --skill Commenting Intent. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is Commenting Intent popular?
It lives in obra/clank, which has 43 GitHub stars and 26 forks.
Related skills
Gardening Skills Wiki
43obra/clank
Maintain skills wiki health - check links, naming, cross-references, and coverage
Remembering Conversations
43obra/clank
Search previous Claude Code conversations for facts, patterns, decisions, and context using semantic or text search
Brainstorming Ideas Into Designs
43obra/clank
Interactive idea refinement using Socratic method to develop fully-formed designs
Debug to Fix
62ElliotJLT/Claude-Skill-Potions
When debugging frustration appears ("why isn't this working?", "it should work", "I don't understand"), orchestrate the full debug cycle: clarify → investigate → fix → verify. Prevents the common failure of jumping to fixes before understanding the problem. An elixir that chains rubber-duck and prove-it with investigation.
Code Walkthrough
36dariia-m/my_claude_skills
Interactive step-by-step code walkthrough for entire codebases (single or multi-file). Explains each section's logic, assumptions, and data transformations, then RUNS the code and shows actual output - dataframe dimensions, head(), model summaries, plot descriptions, file previews. Pauses after each section for questions. Use whenever the user says "walk through", "explain", "go through", "break down", "review", "understand", "what does this code do", "help me understand this script", "annotate", "explain step by step", or "walk me through the codebase". Also trigger if someone just points at
Designing Before Coding
43obra/clank
Design in pseudocode first, iterate approaches, then translate to code
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.