evergreen-writing

Applies evergreen documentation principles when writing Markdown docs and code comments.

Updated Oct 14, 2024
One-click install
npx skills add https://github.com/tktcorporation/food-shop-search --skill evergreen-writing-tktcorporation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: evergreen-writing
Source: https://github.com/tktcorporation/food-shop-search/tree/main/.claude/skills/evergreen-writing
Command: npx skills add https://github.com/tktcorporation/food-shop-search --skill evergreen-writing-tktcorporation

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Documentation and code comments often become stale or misleading because they contain time-dependent phrases, historical references, duplicated information, or restate what the code already shows. This Skill provides a checklist-driven workflow that keeps Markdown documents and code comments accurate and understandable for readers months later. ## Core Features & Use Cases - Four-phase writing workflow: Identify the reader and purpose before writing, apply Evergreen/Why-First/SSOT/Reader-Friendly principles while writing, then run three self-check rounds after writing. - Time-dependency detection: Grep commands catch phrases like "previously", "currently", "planned", PR numbers, commit SHAs, and personal names so they can be rewritten as timeless fact statements. - SSOT enforcement: Checks for duplicated information across files with grep and converts duplicates into references to a single source of truth. - Use Case: When asked to update a README, add a rule to .claude/rules/, write JSDoc for an exported function, or draft a PR description, run this checklist before and after editing to avoid documentation lint violations. ## Quick Start Use the evergreen-writing skill to review and rewrite this README section so it contains no time-dependent expressions or duplicated content.

Frequently Asked Questions about evergreen-writing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write documentation that does not become outdated?▼

Avoid time-dependent words like "previously", "currently", and "planned", and never reference PR numbers, commit SHAs, dates, or author names. State facts as timeless declarations and explain the reasoning behind decisions instead of describing what the code does.

What is the SSOT principle in technical documentation?▼

SSOT (Single Source of Truth) means each piece of information lives in exactly one place. Before writing, grep the repository for existing coverage of the topic; update the existing document or add a reference to it rather than duplicating content.

When should I add comments to code versus leaving it uncommented?▼

Add comments only to public exported functions (JSDoc/docstring) and non-trivial logic, focusing on why a decision was made. Skip comments on self-evident getters or functions whose types already explain behavior, since those comments add noise.

Does this checklist apply to changelogs and release notes?▼

No. CHANGELOG files, .changeset entries, and docs/plans/ are explicitly out of scope because historical records legitimately contain dates and time references. The evergreen rules target living documents like READMEs, design docs, and rules files.

Why does my documentation lint hook flag time-dependent phrases?▼

Post-edit doc-lint hooks and structured lint rules detect time-dependent expressions and history references in Markdown and code comments. Rewrite flagged phrases as fact statements, for example changing "we previously used X" to "we use Y because of reason Z".