Commenting Intent

Comment WHY code exists and non-obvious decisions, not WHAT code does (mechanics)

43 stars 26 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add obra/clank --skill Commenting Intent
Manual install
git 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-Intent

Personal 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:**
Read the full skill on GitHub

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

43

obra/clank

Maintain skills wiki health - check links, naming, cross-references, and coverage

Other26

Remembering Conversations

43

obra/clank

Search previous Claude Code conversations for facts, patterns, decisions, and context using semantic or text search

AI, LLMs & Agents26

Brainstorming Ideas Into Designs

43

obra/clank

Interactive idea refinement using Socratic method to develop fully-formed designs

Software Development26

Debug to Fix

62

ElliotJLT/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.

Software Development

Code Walkthrough

36

dariia-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

Software Development11

Designing Before Coding

43

obra/clank

Design in pseudocode first, iterate approaches, then translate to code

Software Development26

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.