comment-code
コードにコメント・ドキュメンテーションコメントを追加・補強する。「コメント追加して」「コメント書いて」 「コメントを補強して」「JSDoc 付けて」「docstring 付けて」「ドキュメンテーションコメント付けて」で使用。 パッケージ・サービス視点での役割境界、呼び出し元・呼び出し先の前提と契約、他ファイル・他サービスからの 文脈を「その場で読める」形で残す。コード自体は変更しない（実装変更は implement-issue へ）。 詳細規約は code-comment-style、コミット作成は create-commit、CLAUDE.md 同期は update-docs を参照。
- Installs
- 1.5K
- Last 24h
- +18
- Trending rank
- #6224
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/fandhe-ai/agent-cli-skills --skill comment-code- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads comment-code automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
comment-code
コードにコメント・ドキュメンテーションコメントを追加・補強する。コードの実装は変更せず、役割の境界・呼び出し元の前提・返値の契約・他所との依存を「その場で読める」形で記述することが目的。
使い方
comment-code <対象ファイルまたはディレクトリ> [--lang <言語>]
引数を省略した場合は git diff HEAD の差分ファイルを対象とする。
--lang を指定するとドキュメンテーションコメントの形式（JSDoc / docstring / rustdoc 等）を優先言語として扱う。指定がない場合は拡張子から自動判定する。
前提条件
- 対象ファイルが読み取り可能な状態であること
- Git リポジトリ内であること（引数省略時に
git diff HEADを使用するため）
フロー
Step 1: 対象ファイルを特定する
引数が指定された場合はそのファイル・ディレクトリを対象にする。
# 引数なしの場合: 直近の差分ファイルを列挙（staged / unstaged 両方を HEAD と比較）
git diff HEAD --name-only
# untracked（新規未追跡）ファイルも対象にしたい場合
git ls-files --others --exclude-standard
対象が空（変更なし・引数なし）の場合はユーザーに対象を確認する。
Step 2: 対象の役割をコードベースから調査する
このステップが最も重要。 ファイル単体だけを見るのではなく、システム全体の中での位置づけを把握する。
2-1: 呼び出し元を調査する
対象ファイルが公開するシンボル（関数・クラス・型・定数）をコードベース全体で検索し、どのレイヤー・どのサービスから呼ばれているかを把握する。
# シンボル名で呼び出し元を検索（例: exportされる関数名）
grep -rn "対象シンボル名" --include="*.ts" --include="*.js" .
2-2: import・依存関係を確認する
対象ファイルが依存している外部モジュール・サービス・設定を把握する。
# import 文の一覧
grep -n "^import\|^from\|require(" 対象ファイル
2-3: パッケージ・サービス境界を確認する
package.json・go.mod・Cargo.toml等でパッケージ名・公開 API を確認する- サービス間通信（HTTP クライアント・イベント発行・メッセージキュー）が含まれる場合は接続先を特定する
- 認証・認可のミドルウェアやセッション管理と対象の関係を確認する
2-4: 既存コメントスタイルを確認する
同じファイル・同じパッケージ内の既存コメントを読み、スタイル（JSDoc / docstring / rustdoc 等）・言語（日本語/英語）を把握する。
Step 3: コメントを追加・補強する
Step 2 で把握した「他ファイル・他サービスからの観点」をコメントとして書き込む。
コメントスタイルの規約（中心思想）
対象リポジトリに .claude/rules/code-comment-style.md が存在する場合はそちらを優先して従う。存在しない場合は以下の要点に従う。
書くべき内容:
| 観点 | 書く内容 |
|---|---|
| 役割・責務の境界 | 「このモジュールは〜サービスの〜境界を担う」「〜パッケージの公開インターフェースとして機能する」 |
| 呼び出し元の文脈 | どのレイヤー・どのサービスから呼ばれるか。呼び出し元が前提とする状態・権限 |
| 呼び出し先との契約 | 何を保証して返すか。エラー・例外の条件とその意味（null を返すのか例外を投げるのか等） |
| 他ファイル・他サービスとの依存 | 読み手がファイルを跨がないと見つけられない外部依存・設定・共有状態 |
| 非自明な制約・背景・why | なぜその実装になっているか。背景・制約・契約・仕様上の制限 |
書かないもの:
- シグネチャ・型から自明な逐語的説明（what の言い換え）
- 実装と乖離して陳腐化しやすい重複情報
- 解決済みの経緯だけを残したコメント
ドキュメンテーションコメント（言語別慣習）
言語の慣習に従った形式を使用する:
- TypeScript / JavaScript: JSDoc (
/** ... */) - Python: docstring (
"""...""") - Rust:
///(アイテム) ///!(モジュール) - Go:
// FuncName ...形式 - Java / Kotlin: Javadoc (
/** ... */) - その他: 言語公式ドキュメントの慣習に従う
先頭の要約行に「役割・境界」を書き、本文に呼び出し元・呼び出し先の文脈・非自明な制約を追記する。
インラインコメント
why（なぜその実装か）を書く。what はコードが示している。制約・背景・仕様上の都合は該当行またはブロックの直前に書く。参照すべき外部情報（Issue 番号・仕様書 URL）は積極的に記載する。
良い例・悪い例
悪い例（what の逐語的な言い換え）:
/**
* ユーザーIDを受け取り、ユーザー情報を返す。
* @param userId ユーザーID
* @returns ユーザー情報
*/
function getUser(userId: string): User | null { ... }
良い例（役割と他所からの観点を含む）:
/**
* 認証レイヤーの公開インターフェース。API ハンドラーから呼ばれ、
* セッション検証済みの呼び出しのみを前提とする（未認証は上流ミドルウェアで遮断）。
*
* UserRepository に委譲し、DB から取得した値を返す。
* 存在しない場合は null を返す（例外は投げない）——
* 呼び出し元は null チェックを必ず行うこと。
*
* 注: soft delete されたユーザーも null として扱う（仕様: issue #142）。
*/
function getUser(userId: string): User | null { ... }
Step 4: 自己チェックを行う
追加・補強したコメントを以下の観点でレビューする。
内容の正確性
- 自明な逐語的説明・what の言い換えになっていないか
- 実装と乖離した内容を書いていないか（シグネチャと矛盾しないか）
- Step 2 の調査結果（呼び出し元・依存関係）が正しくコメントに反映されているか
セキュリティ（必須チェック）
- コメントにAPIキー・トークン・パスワード等の秘密情報を書いていないか
- コメントに個人情報（PII）を直接記載していないか（ユーザーIDの例示等）
- 認証・認可の前提条件を誤解を招く形で記述していないか（「認証不要」等の誤記）
- セキュリティ上の制約・権限の前提は明確かつ正確に記述されているか
上記チェックで問題が見つかった場合は、コメント内容を修正してから次に進む。
日本語スタイル
- 常体（だ・である調）で記述されているか
- コマンド・識別子・ファイル名は英語のまま（翻訳しない）
- 絵文字の多用がないか
Step 5: 差分を提示して報告する
変更内容を差分形式で提示し、以下の形式でレポートする。
## comment-code 完了報告
### 対象ファイル
- `path/to/file.ts`（追加: N 件、補強: M 件）
### 追加したコメントの観点
- 呼び出し元: [どこから呼ばれるかを明記した箇所]
- 呼び出し先との契約: [返値・エラー条件を明記した箇所]
- 非自明な制約・背景: [why を記述した箇所]
### セキュリティチェック
- 結果: ✅ 問題なし / ⚠️ 警告あり（詳細）
### 次のアクション
- コミットする場合: create-commit スキルを使用
- CLAUDE.md を更新する場合: update-docs スキルを使用
コミットは create-commit スキルへ委譲する（このスキル自身はコミットを行わない）。
検証
コメント追加後、以下で確認する。
git diff HEAD
- コードのロジック（関数本体・制御フロー）が変更されていないこと
- 追加したコメントが実装と矛盾していないこと
- Step 4 の自己チェックリストがすべて通過していること
よくある失敗
| 問題 | 回避策 |
|---|---|
| シグネチャ・型から自明な内容を逐語的に書く（what の言い換え） | 「なぜその実装か」「呼び出し元の前提」など自明でない情報のみ書く |
| 呼び出し元を調査せず推測でコメントを書く | Step 2 で必ず grep で呼び出し元を確認してから記述する |
| コメントにシークレット・個人情報を混入する | Step 4 のセキュリティチェックで秘密情報・PII がないことを確認する |
| コードのロジックを「整理しながら」変更してしまう | 実装変更が必要な箇所はコメントで TODO を残し、implement-issue へ誘導する |
注意事項
- コードのロジックは変更しない — コメントの追加・補強のみ行う。実装に問題があると判断した場合は
implement-issueスキルへ誘導する - コメントは実装と同期させる — 既存コメントが実装と乖離している場合は修正する（乖離したコメントは正確なコメントより有害）
- 詳細規約は対象リポジトリに従う —
.claude/rules/code-comment-style.mdが存在する場合はそちらを優先する。本スキルの Step 3 の要点はそのファイルが未配備の場合のフォールバックとして機能する - AI エージェントも読み手と想定する — 「他のファイルを参照すれば分かる」は通用しないと想定して書く。Claude 等のエージェントはコメントを主要な文脈源として使用する
--no-verifyなど pre-commit フック回避は禁止。コミット時にフックが失敗した場合は原因を調査・修正してから再実行する
FAQ
What does the comment-code skill do?
コードにコメント・ドキュメンテーションコメントを追加・補強する。「コメント追加して」「コメント書いて」 「コメントを補強して」「JSDoc 付けて」「docstring 付けて」「ドキュメンテーションコメント付けて」で使用。 パッケージ・サービス視点での役割境界、呼び出し元・呼び出し先の前提と契約、他ファイル・他サービスからの 文脈を「その場で読める」形で残す。コード自体は変更しない（実装変更は implement-issue へ）。 詳細規約は code-comment-style、コミット作成は create-commit、CLAUDE.md 同期は update-docs を参照。
How do I install comment-code?
Run npx skills add https://github.com/fandhe-ai/agent-cli-skills --skill comment-code in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/comment-code/ (personal) or .claude/skills/comment-code/ (project).
Which AI agents can use comment-code?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is comment-code safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains comment-code?
It is published by fandhe-ai in fandhe-ai/agent-cli-skills. It has 1,544 recorded installs.
More from fandhe-ai/agent-cli-skills
create-plan
fandhe-ai/agent-cli-skills
実装タスクの計画を /local-plans/ .md に作成する。「計画立てて」「設計して」「実装方針を考えて」「タスク分解して」で使用。 Explore Agent でコードベースを先に調査し、検証可能な粒度・並列実行可能な単位で記述する。 plan-verifier Agent で検証可能な標準フォーマット（背景・現状・設計・ファイル構成ツリー・実装ステップ・検証方法）に従う。 実装消化は implement-issue、Issue 化は create-issue-tree（未導入なら create-issue）を参照。
create-commit
fandhe-ai/agent-cli-skills
Conventional Commits 形式で git コミットを作成する。staged 差分から type/scope を推定し、breaking change やシークレット混入 (.env 等) を検出。pre-commit フックを必ず通す (--no-verify 不可)。「コミットして」「git commit」「変更を記録して」などで使用。
create-pr
fandhe-ai/agent-cli-skills
Conventional Commits 形式で GitHub PR を作成する。OWASP Top 10 のセキュリティチェック必須で、問題があれば PR 作成を中止。Summary/Test plan/Design を含む body を生成。「PR 作って」「プルリク」「gh pr create」などで使用。別リポジトリ (upstream) への貢献は contribute-skill。
implement-issue
fandhe-ai/agent-cli-skills
GitHub Issue を読み込み、/local-plans/ - .md に詳細計画を作成してユーザー承認後にコードを実装する。実装後はセキュリティレビュー (OWASP Top 10) → テスト実行 → Conventional Commits でコミット。Issue 番号や URL を渡された実装依頼、「Issue N を実装して」「この Issue を着手」などで使用。
create-issue
fandhe-ai/agent-cli-skills
GitHub Issue を親子構造 (sub-issues) で作成する。gh issue create で親・子 Issue を生成し、gh api .../subissues で親子関係を紐付ける。タイトルは Conventional Commits 形式 (feat:, fix: 等) を推奨。「Issue 作って」「タスクを分解して Issue 化」などで使用。
implement-review
fandhe-ai/agent-cli-skills
コード変更 (git diff) の品質・アーキテクチャ準拠・セキュリティ (OWASP Top 10) を Agent ツール委譲で読み取り専用レビューする。コミット前/PR 作成前のセルフレビュー、「変更をレビューして」「コードレビューして」などで使用。GitHub PR のレビューには implement-review-pr を使用。
Popular ai & agents skills
google-agents-cli-publish
google/agents-cli
This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).
google-agents-cli-eval
google/agents-cli
This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).
skill-creator
anthropics/skills
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
codex-pet
prime-skills/runcomfy-agent-skills
Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.
full-output-enforcement
leonxlnx/taste-skill
Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.
executing-plans
obra/superpowers
Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available