motoedie/code-comments
ai-tools/skills/code-comments/SKILL.md
Add, review, or rewrite code comments so they explain intent, invariants, branch rationale, and multi-step flows without narrating obvious syntax. Use when documenting newly added or recently changed code, converting line-by-line comments into concise block comments, checking whether comment density is too sparse or too heavy, or making non-obvious branches, scripts, and side effects easier for reviewers to scan.
development
Updated Apr 19, 2026
$ install --global
skillsauthnpx skillsauth add motoedie/.dotfiles code-commentsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 19, 2026, 4:06 AM6.7s2 files scanned
SKILL.md
- name:
- code-comments
- description:
- Add, review, or rewrite code comments so they explain intent, invariants, branch rationale, and multi-step flows without narrating obvious syntax. Use when documenting newly added or recently changed code, converting line-by-line comments into concise block comments, checking whether comment density is too sparse or too heavy, or making non-obvious branches, scripts, and side effects easier for reviewers to scan.
Code Comments
Comment $ARGUMENTS.
If $ARGUMENTS is empty, focus on the code most recently modified in the current session or diff.
Style
- Prefer comments that explain intent over comments that restate syntax.
- Place one short comment before a compact non-obvious block, such as an
ifbranch, early return, or transformation step. - Split longer functions into phases and comment each phase instead of commenting every line.
- Explain why a block exists, what invariant it preserves, what side effect it triggers, or why a branch is special.
- Comment embedded shell, SQL, or multi-step string scripts by phase when the sequence is important.
- Match the surrounding codebase's tone and comment density unless the user asks to change it.
Avoid
- Do not narrate obvious assignments, conditionals, or loops.
- Do not duplicate what a good function or variable name already says.
- Do not add filler comments just to increase coverage.
- Do not leave stale comments after changing code.
- Do not use comments to excuse confusing code when a small simplification would make it clearer.
Process
- Read the surrounding function and identify the parts that are not obvious from the code alone.
- Remove or rewrite comments that merely describe mechanics.
- Add comments at block boundaries, branch boundaries, and phase boundaries.
- Use finer-grained comments inside a function only when a block contains multiple distinct steps.
- Re-read the result and make sure the comments help a reviewer scan the code faster.
Heuristics
- Good comment: explain why filtered exports must keep the original snapshot id in the final package.
- Weak comment: explain that
p1is set to-1whensystemLogsis true. - Good comment: describe that a temp directory isolates an unpacked export before repackaging.
- Weak comment: describe that
fs.ensureDir()creates a directory.
Decision Rule
If a section seems to need a comment for every line, step back and either:
- replace line-by-line comments with one block comment, or
- simplify the code before adding comments.
Related Skills
motoedie/tdd
development
VerifiedTrustedCommunity
Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
SKILL.mdUpdated Apr 19, 2026
motoedie/code-simplify
development
VerifiedTrustedCommunity
Simplify and refine existing code for clarity, consistency, and maintainability while preserving exact functionality. Use after writing or modifying code, when asked to simplify or clean up code without changing behavior, or when recently touched code should be made easier to read and more consistent with project standards.
SKILL.mdUpdated Apr 19, 2026
openclaw/openclaw-secret-scanning-maintainer
development
VerifiedTrustedCommunity
Maintainer-only workflow for handling GitHub Secret Scanning alerts on OpenClaw. Use when Codex needs to triage, redact, clean up, and resolve secret leakage found in issue comments, issue bodies, PR comments, or other GitHub content.
357,764SKILL.mdUpdated Apr 15, 2026
openclaw/openclaw-release-maintainer
development
VerifiedTrustedCommunity
Maintainer workflow for OpenClaw releases, prereleases, changelog release notes, and publish validation. Use when Codex needs to prepare or verify stable or beta release steps, align version naming, assemble release notes, check release auth requirements, or validate publish-time commands and artifacts.
357,764SKILL.mdUpdated Apr 10, 2026