ALT https://github.com/karlhorky/agent-skills/pull/2 Add code-comments skill karlhorky 3 hours ago Comments written by AI agents often: lead with the mechanism rather than the reason (the "what" instead of the "why") bury the failure being avoided ("bury the lede") use vague nouns or identifiers from another layer repeat column or field names instead of describing stored values The code-comments skill defines three forms: an action opening with an imperative verb a fact opening with the system or entity it describes a column or field description written as a noun phrase Actions use <verb> <noun> <reason>, except when the action and nearby code make the reason clear. Comments put affected records or entities near the start for faster debugging and use identifiers from the surrounding code so they remain searchable. The skill also covers failure-first comments, matching TSDoc and CREATE TABLE descriptions, comment prefixes, and long background comments. Add action,

ALT https://github.com/karlhorky/agent-skills/blob/main/.agents/skills/code-comments/SKILL.md Code Comments Overview Write comments for what the code does not express, usually a reason or behavior. Most comments take one of three forms: Action: start with an imperative verb Fact: omit the action and state a reason or behavior with its subject first Description: use a noun phrase for what a database field or TypeScript property stores Write actions as <verb> <noun> <reason>. Common words before an explicit reason include because, so, so that, to and for. Exceptions: Omit <reason> only when the action and nearby code make it clear Use one sentence with no trailing period, wrapping it across lines when needed. Use multiple paragraphs only when the comment requires background. Announce at start: "I'm using the code comments skill." Examples of Code Comments Start actions with an imperative verb Example 1: omit a reason clear from nearby code Good: -- Sort optional lectures after other r

ALT Put debugging details first for scannability Comments are often read while debugging, so two things are critical for speed of scanning: 1. The first word of the comment 2. The words near the start of the comment Start actions with a verb followed by affected records or entities. Start facts with affected records or entities. Put generic conditions and reasons afterward. Example 1: action verb directly followed by affected records Good: -- Exclude Tech Fundamentals Foundations (Immersive) cohorts, which -- never had graduation events, so their certificates have no end -- date to print Example 2 (bad): put a generic condition first Bad: -- Return no certificate for Immersive cohorts with no graduation event, -- because there is no end date to print - currently only Tech -- Fundamentals Foundations (Immersive) cohorts Why bad: - Names the affected cohorts on the last line - Starts with a generic condition that does not identify the affected cohorts

ALT Name failures with Avoid or Prevent Start workaround, guard and fallback comments with Avoid or Prevent. Follow the action form above, naming the failure before the reason (<Avoid/Prevent> <failure> <reason>). Common words before the reason include by and with. Example 3: name the failure before the reason Good: -- Avoid signup failure when the browser reports a time zone missing -- from time_zones by falling back to 'Etc/UTC' Example 4 (bad): start with the fallback Bad: -- Fall back to 'Etc/UTC' Why bad: - Starts with the fallback instead of the failure - Omits the missing time zone reason