Writing Evergreen Comments
Write comments explaining WHAT and WHY, never temporal context or history
Install
npx skills add obra/clank --skill Writing Evergreen Commentsgit 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-CommentsPersonal 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>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
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
Writing Plans
43obra/clank
Create detailed implementation plans with bite-sized tasks for engineers with zero codebase context
Technical Blog Post
38sam-dumont/claude-skills
Use when writing a technical blog post from raw project data like research notes, session logs, Reddit/LinkedIn drafts, code, hex dumps, or screenshots. Also use when Sam says "write a blog post about [project]" or "turn this into a post".
Architectural Proposals
45Azure-Samples/agent-skills-dotnet-demo
How to write comprehensive architectural proposals that drive alignment before code is written
Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.