Writing Evergreen Comments

Write comments explaining WHAT and WHY, never temporal context or history

43 stars 26 forksWriting & Content

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add obra/clank --skill Writing Evergreen Comments
Manual install
git clone --depth 1 https://github.com/obra/clank.git /tmp/clank
mkdir -p ~/.claude/skills
cp -r /tmp/clank/skills/coding/writing-evergreen-comments ~/.claude/skills/Writing-Evergreen-Comments

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Writing Evergreen Comments

## Overview

Comments documenting change history or implementation improvements become stale and confusing. "// Refactored from legacy system" tells nothing about current purpose.

**Core principle:** Comments explain WHAT code does or WHY it exists, never how it's better than before.

**Violating the letter of this rule is violating the spirit of documentation.**

## When to Use

**Use for:**
- File headers (ABOUTME pattern)
- Function/class documentation
- Complex logic explanation
- Non-obvious WHY reasoning

**Use ESPECIALLY when:**
- Refactoring code (tempted to document the change)
- Replacing implementations (tempted to explain old vs new)
- Improving code (tempted to say "better" or "enhanced")
- Reviewing old comments (tempted to preserve history)

## The Rules

### NEVER Document Changes or History

Comments describe present state, not past or transitions.

<Bad>
```typescript
// Refactored from the old validation system
// Now uses Zod instead of manual checking
class Validator {
  validate(data: unknown) { }
}

// Improved error handling - used to just throw
function processRequest() { }

// Recently moved from utils/ to core/
export function helper() { }
```
</Bad>

<Good>
Read the full skill on GitHub

Details

Skill name
Writing Evergreen Comments
Repository
obra/clank
Path
skills/coding/writing-evergreen-comments/SKILL.md
Repo updated
9 October 2025

FAQ

What does the Writing Evergreen Comments skill do?

Write comments explaining WHAT and WHY, never temporal context or history

How do I install the Writing Evergreen Comments skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add obra/clank --skill Writing Evergreen Comments. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Writing Evergreen Comments popular?

It lives in obra/clank, which has 43 GitHub stars and 26 forks.

Related skills

Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.