An Agent Skill for keeping code comments minimal and high-signal. It teaches coding agents to remove comments that narrate visible code while preserving rationale, constraints, tradeoffs, required directives, and other information the code cannot express.
The skill follows the open Agent Skills specification and works with both OpenAI Codex and Claude Code.
npx skills add noah4520/concise-comments --skill concise-comments --global --agent codex --yesnpx skills add noah4520/concise-comments --skill concise-comments --global --agent claude-code --yesBoth commands install the skill globally. For a project-local installation, omit --global.
Codex and Claude Code can activate the skill automatically during code authoring, implementation, refactoring, debugging, and review tasks that may add or touch comments.
Use $concise-comments to review the comments in this diff.
/concise-comments Review the comments in this diff.
- Delete comments that restate names, types, assignments, or visible control flow.
- Keep rationale, constraints, tradeoffs, warnings, and non-obvious operational facts.
- Prefer clearer code when a name or structure can replace narration.
- Keep required directives, legal notices, generated-file markers, and mandated API documentation.
- Avoid arrow-style prose, label-heavy comments, parenthetical pile-ups, and code-level ticket references.
- Keep TODOs, commit subjects, and short change summaries direct.
skills/concise-comments/
├── SKILL.md
└── agents/
└── openai.yaml
SKILL.md is the cross-agent source of truth. agents/openai.yaml adds optional Codex UI metadata and is safely ignored by other compatible agents.
npm testThe validation checks the portable frontmatter, naming constraints, unresolved placeholders, and Codex UI metadata.
This repository follows the common structure and progressive-disclosure guidance from: