# Trim Comments

> Use when asked to trim, shorten, reduce, or clean up code comments or docstrings, including requests to make comments lighter or less AI-generated

- Skill: `samelhagdev/trim-comments` (Agent Skill)
- Install (CLI): `npx skillmds@latest add samelhagdev/trim-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samelhagdev/trim-comments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: SamElhagDev (https://skillmd.com/u/samelhagdev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/samelhagdev/trim-comments

---


# Trim Comments

## Overview

Cuts comments to what a careful human would write. Only comment and docstring lines change.

## Scope

1. Run `git status --short` and `git diff -U0 HEAD`.
2. Pick the scope:
   - Request says "across the repo" or similar: every file from `git ls-files`
   - Otherwise: comments on lines added or changed in `git diff -U0 HEAD`, plus all comments in untracked files. A comment block is in scope when any of its lines is.
3. Leave out `.specify/`, `wwwroot/lib/`, `node_modules/`, `Migrations/`, and generated or minified files.
4. Count the comment and docstring lines in scope. If the count is 0 and the request wasn't repo-wide, reply `Nothing to trim in uncommitted changes. Trim the whole repo instead?` and stop.

## What each comment becomes

| Comment | Becomes |
|---|---|
| Restates what the code shows, or tells its history ("previously", "now uses", "before this existed") | Removed |
| Explains why: a reason, constraint, pitfall, or workaround | Kept at 1 or 2 lines, on the line it explains |
| Wrong about what the code does | Corrected or removed, and reported |
| Docstring or `///` block | One line: `"""..."""` or `/// <summary>...</summary>`. Its why moves to a comment on the line it explains, or above the first body line when it covers the whole function. Removed when the line would only repeat the name, unless that leaves the body empty; then the one line stays |
| Banner like `# ── Setup ──` or `/* ===== FONTS ===== */` | Plain label: `# Setup`, `/* Fonts */` |
| Em-dash | `;`, `:`, `.` or `,` |
| Spec Kit IDs (`T032`, `US3`, `FR-008`, `SC-007`, `Principle I`) | ID removed, sentence kept; the whole comment goes when it only tracks a task |
| Functional: `# noqa`, `# type: ignore`, `#region`, `// <auto-generated>`, `/// <inheritdoc />`, shebang, encoding line, license header | Unchanged |
| Commented-out code | Unchanged, and reported |

## Checks

1. Python files changed: `python -m compileall -q <files>`, then `python -m pytest -q` when the repo has tests. .NET files changed: `dotnet build`.
2. Read the resulting `git diff`: only comment text, docstrings, and blank lines differ. Put back any code that changed.

## The reply

Exactly these lines, in order:

1. `Trimmed comments in <n> files: <before> to <after> comment lines.`
2. Only when a wrong comment was corrected or removed: `Fixed wrong comments:` then `- <file>:<line> <what it claimed; what the code does>`
3. Only when commented-out code is in scope: `Commented-out code left in place:` then `- <file>:<line>`
4. `Checks: <results>` (e.g. `compileall clean, tests pass`), or `Checks: none found; review the diff.`

Changes stay unstaged and uncommitted.