code-comments

A personal Claude skill that teaches the agent to write code comments to a consistent quality bar (OpenZeppelin-grade), in two modes:

• Passive — applied automatically while the agent writes or edits code.
• Active — invoked on demand to review and fix existing comments (/code-comments [file|diff]).

See DESIGN.md for the full rationale and the agreed rules. The skill itself is SKILL.md plus the files under references/.

Layout

SKILL.md            core: principles, taxonomy, form, hygiene, two modes
references/         detailed rules, examples, active-mode workflow
eval/               test methodology + run log
.baseline/          gitignored OZ checkout used for testing (not part of the skill)

Testing

The skill is tested TDD-style against OpenZeppelin (a quality bar the user trusts). See eval/methodology.md. In short: strip comments from a real OZ file, have a sub-agent re-write them (with vs without the skill), and compare to the OZ original.

Install

Installed as a copy, not a symlink/junction — deliberately. This repo keeps getting refined, and a link would push every in-progress edit straight into live sessions (where the skill is in use). A copy decouples the deployed version from development.

Deployed state:

• SKILL.md + references/ copied to ~/.claude/skills/code-comments/.
• The global ~/.claude/CLAUDE.md "Comment style preference" section points at the skill.

To deploy an update: re-copy SKILL.md and references/ over the installed copy. Do not copy the dev-only files (.baseline/, eval/, DESIGN.md, .git/, CLAUDE*.md).