Weed comment

Skill gitt510/agent-skills/skills/weed-comment

Remove context-leak prose from comments and docstrings in AI-agent-written code: edit-history narration, reviewer-directed self-justification, session references, redundant code restatement, and commented-out code. Preserve durable contract documentation, constraints, non-obvious rationale, business rules, TODO/FIXME, and tool directives. Use after an agent coding session, before committing agent-written changes, when a diff review flags comment noise, or when the user says "clean up the comments", "remove AI comments", "comment slop", "コメント整理して", "コメント抜いて", or invokes /weed-comment. Edit comments and docstrings only; never change executable code or perform a general simplify pass.From its SKILL.md

Install

npx -y skills add gitt510/agent-skills --skill weed-comment

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

23 days oldThe repository was created 23 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.2 KB, ~1.1k tokens by cl100k_base, as published. Nobody here has run it

weed-comment

コメントと docstring は、変更の弁明ではなく次の読者へ残す documentation として扱う。 session にしか意味のない文を削り、コードだけでは伝わらない情報を残す。

Core test

各文を、session を見ていない第三者としてコードと一緒に読む。

コードの利用・保守に必要で、文だけで意味が完結するなら残す
「どの変更の話か」「誰に説明しているのか」が必要なら削る
名前・signature・処理を言い換えるだけなら削る

迷ったら、この test に戻る。

Scope

default は diff-only とする。staged + unstaged の patch が追加・変更した comment / docstring だけを対象にし、同じ file の既存 documentation へscopeを広げない。

repo 全体やnamed directoryは、明示的に頼まれた場合だけ対象にする。

Workflow

対象scopeのdiffを読み、追加・変更されたcommentとdocstringを拾う。
block単位ではなく文単位でCore testを適用する。
weedだけのblockは削除し、keeperが混在するblockは最小限のdocumentationへ圧縮する。
keeperの文言は維持する。混在文からkeeper部分を切り出す場合だけ、文として成立する最小限の書き直しを行う。
final diffを読み、executable codeと無関係なformattingが変わっていないことを確認する。
weedがなければ変更を作らず、「weedなし」と報告する。

Remove

編集履歴 — "added" / "removed" / "changed" / "updated" / "now handles" / "previously"。履歴はgitが保持する
レビュワーへの自己正当化 — "this is safe because…" / "correctly handles…"
session参照 — "as discussed" / "as requested" / "per review feedback"
コードの言い換え — 名前・signature・制御構造から明らかな説明
commented-out code — 復元可能な履歴はgitが保持する

Preserve

コードが表現できない制約やinvariant
非自明な理由、business rule、side effect
public contractのうち、signatureだけでは明らかでないbehavior、error、usage
fixtureの生成元や暗黙の呼び出し元など、SoTへの導線
TODO / FIXMEなどのwork marker
linter / formatter / coverage / generated-codeのdirective

Docstrings

docstringにもCore testをそのまま適用する。public APIだから無条件に残すのではなく、利用者に必要なcontractだけを保持する。conventionやtoolが形式を要求する場合は、その要件を満たす最小のdocstringを残す。

internal objectの名前やsignatureを言い換えるだけで、tooling上も不要なら、docstring全体を削除してよい。逆に、meaningfulなpublic contractを機械的に一行へ縮めない。

Compression example

❌ 「site_id は各 target の持ち物として宣言する（値の一致は偶然で、共有は前提にしない）。site は stg「…」、prd「…」。mode 設定は {target}-gptConfig にある。」

✅ 「stg / prd の site_id の一致は偶然で、共有は前提にしない」

Boundaries

commentとdocstringだけを編集する。executable code、挙動、無関係なformattingに触れない
削除すると必須blockが空になる場合（passだけのblockなど）は、syntaxを壊さない
simplify / over-engineering reviewへscopeを広げない

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.