[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F62EP0WC5TP53TZ2F6WM29":3,"skill-same:01M7F62EP0WC5TP53TZ2F6WM29":43},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":5,"forksCount":14,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":28,"install":29,"resources":42},"01M7F62EP0WC5TP53TZ2F6WM29","code-comments",null,"Write code comments that explain why, never what, and strip comment noise from existing code: comment constraints, invariants, workarounds, and rejected alternatives; delete narration, section banners, and restated names; match the codebase's comment density. Use whenever writing a code comment, writing code that may need comments, editing code that has them, writing docstrings or API docs, or asked to clean up, reduce, or improve comments. Pairs with naming (the fix for a comment explaining a bad name is a better name) and writing-docs (the same what-versus-why judgment in docs).","gauravjuvekar\u002Fagent-skills","gauravjuvekar","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F2271906?v=4","01M7F625F465JZDHRTYQTT9JNN","Gaurav Juvekar","01M7F625FNDSSS6BGT77B6R64P",0,"MIT","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills\u002Fblob\u002Fmaster\u002Fcode-comments\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: code-comments\ndescription: \"Write code comments that explain why, never what, and strip comment noise from existing code: comment constraints, invariants, workarounds, and rejected alternatives; delete narration, section banners, and restated names; match the codebase's comment density. Use whenever writing a code comment, writing code that may need comments, editing code that has them, writing docstrings or API docs, or asked to clean up, reduce, or improve comments. Pairs with naming (the fix for a comment explaining a bad name is a better name) and writing-docs (the same what-versus-why judgment in docs).\"\n---\n\n# Code comments\n\nCode is the behaviour. A comment that restates it says nothing and rots: the\ncode gets edited, the comment doesn't, and now the file lies. The only\ncomments worth writing carry what the code cannot: the reason, the\nconstraint, the history. Agents fail in both directions at once, narrating\nevery step (\"\u002F\u002F increment the counter\") while leaving the actual trap (the\nAPI that returns milliseconds where everything else uses seconds)\nundocumented. Default to zero comments, then add back only the ones below.\n\n## When a comment is warranted\n\n- A non-obvious constraint or invariant: \"callers hold the lock\", \"must stay\n  in sync with the enum in proto\u002Fstatus.proto\", \"list is sorted, bisect\n  depends on it\".\n- A workaround, with a link to what it works around: the upstream bug, the\n  broken client version, the platform quirk. Without the link, the next\n  reader can't tell when it's safe to remove.\n- Why an obvious-looking alternative was rejected: \"regex here backtracks\n  catastrophically on real inputs, hence the hand-rolled parser\". This is the\n  comment that stops the next person from \"simplifying\" the code back into\n  the bug.\n- Units, formats, or ranges the type system can't express: \"timeout in\n  milliseconds\", \"amount in cents\", \"0.0 to 1.0 inclusive\".\n- Why risky code is safe: for `unsafe` blocks, lock-free code, and\n  security-sensitive paths, state the invariant the safety rests on and who\n  maintains it: \"SAFETY: ptr was allocated by this Vec and len \u003C= capacity\".\n  Rust's standard library requires these; the discipline transfers to any\n  language where one wrong assumption corrupts memory or leaks data.\n\n## Refactor before you comment\n\nIf none of the above apply and the code still seems to need a comment to be\nunderstood, the fix is code, not prose: a better name, an extracted\nfunction, a stronger type, an assertion. A comment explaining confusing code\npatches the symptom and starts rotting immediately; the rename fixes the\ncause and can't drift.\n\n```go\nvar d int \u002F\u002F days since last refresh\n```\n\n```go\nvar daysSinceLastRefresh int\n```\n\nThe exception is a call site you can't restructure. An argument whose\nmeaning is invisible at the call is best fixed with keyword arguments or an\noptions struct, but when the signature isn't yours to change,\n\n```go\nrender(label, true \u002F* primary *\u002F, false \u002F* disabled *\u002F)\n```\n\nbeats a bare `render(label, true, false)` and beats a comment on the line\nabove, because it can't drift away from the argument it labels.\n\n## What is noise\n\n- Narrating the next line: `\u002F\u002F increment the counter` above `counter += 1`.\n- Section banners: `\u002F\u002F ---- helpers ----`, `\u002F\u002F Validation section`.\n- Restating a name: `\u002F\u002F UserService handles users` on `class UserService`.\n- Comments addressed to the reviewer instead of the next reader: \"fixed the\n  bug here\", \"per feedback\", \"new function to handle retries\", \"changed from\n  the old approach\". These describe the diff, not the code; they are stale\n  the moment the PR merges. If the change history matters, it belongs in the\n  commit message.\n- Comments explaining why your change is correct. Same problem: that is an\n  argument to the reviewer, and it is noise to everyone after.\n\n## Bad, then good\n\n```python\n# Loop through the retries and try the request\nfor attempt in range(5):  # 5 retries\n    resp = fetch(url)\n    if resp.ok:\n        break\n    time.sleep(2 ** attempt)  # exponential backoff\n```\n\n```python\n# Upstream rate-limits bursts; 5 tries with backoff covers their\n# longest observed throttle window (issue #482).\nfor attempt in range(5):\n    resp = fetch(url)\n    if resp.ok:\n        break\n    time.sleep(2 ** attempt)\n```\n\nThree noise comments deleted, one constraint added. The good version has\nfewer comments and more information.\n\n## Docstrings and API docs\n\nA docstring is a contract, not narration: what the function promises\n(arguments, return value, errors raised, side effects, thread-safety), never\nhow the body works. \"Uses a dict internally\" is implementation detail that\nbreaks the doc when the implementation changes. Follow the codebase's\nexisting convention for which symbols get docstrings; a private helper whose\nname says everything doesn't need one just because a linter can count.\n\n## Match the codebase\n\nComment density and idiom are house style like anything else. In a sparsely\ncommented codebase, a fully narrated function is as out of place as a\nreformatted file. Match what surrounds your change: density, tone, doc\ncomment format, tag conventions (`TODO(name):`, `FIXME:`, `# NOTE:`).\n\n## TODOs\n\nA TODO with no owner and no issue link is a wish. Write `TODO(alice): ...`\nor `TODO(#482): ...` so it can be chased, or file the issue and skip the\ncomment. Never leave a TODO describing work the user asked you to finish\nnow.\n\n## Editing existing code\n\n- Remove noise comments in code you are already touching; leave the rest of\n  the file alone. Comment cleanup across untouched code is its own change.\n- Some comments are read by tools, not people: linter and formatter\n  directives (`# noqa`, `eslint-disable-next-line`), coverage pragmas,\n  process tags like ADR references. They say nothing to a reader and are\n  still load-bearing; leave them unless you mean to change what they\n  control.\n- Update any comment your edit makes wrong. A stale comment is worse than\n  none.\n- Never delete a comment stating a constraint you don't understand. It may\n  be the only record of why the code survives production. If it looks wrong,\n  say so to the user instead of removing it.\n","# Code comments\n\nCode is the behaviour. A comment that restates it says nothing and rots: the\ncode gets edited, the comment doesn't, and now the file lies. The only\ncomments worth writing carry what the code cannot: the reason, the\nconstraint, the history. Agents fail in both directions at once, narrating\nevery step (\"\u002F\u002F increment the counter\") while leaving the actual trap (the\nAPI that returns milliseconds where everything else uses seconds)\nundocumented. Default to zero comments, then add back only the ones below.\n\n## When a comment is warranted\n\n- A non-obvious constraint or invariant: \"callers hold the lock\", \"must stay\n  in sync with the enum in proto\u002Fstatus.proto\", \"list is sorted, bisect\n  depends on it\".\n- A workaround, with a link to what it works around: the upstream bug, the\n  broken client version, the platform quirk. Without the link, the next\n  reader can't tell when it's safe to remove.\n- Why an obvious-looking alternative was rejected: \"regex here backtracks\n  catastrophically on real inputs, hence the hand-rolled parser\". This is the\n  comment that stops the next person from \"simplifying\" the code back into\n  the bug.\n- Units, formats, or ranges the type system can't express: \"timeout in\n  milliseconds\", \"amount in cents\", \"0.0 to 1.0 inclusive\".\n- Why risky code is safe: for `unsafe` blocks, lock-free code, and\n  security-sensitive paths, state the invariant the safety rests on and who\n  maintains it: \"SAFETY: ptr was allocated by this Vec and len \u003C= capacity\".\n  Rust's standard library requires these; the discipline transfers to any\n  language where one wrong assumption corrupts memory or leaks data.\n\n## Refactor before you comment\n\nIf none of the above apply and the code still seems to need a comment to be\nunderstood, the fix is code, not prose: a better name, an extracted\nfunction, a stronger type, an assertion. A comment explaining confusing code\npatches the symptom and starts rotting immediately; the rename fixes the\ncause and can't drift.\n\n```go\nvar d int \u002F\u002F days since last refresh\n```\n\n```go\nvar daysSinceLastRefresh int\n```\n\nThe exception is a call site you can't restructure. An argument whose\nmeaning is invisible at the call is best fixed with keyword arguments or an\noptions struct, but when the signature isn't yours to change,\n\n```go\nrender(label, true \u002F* primary *\u002F, false \u002F* disabled *\u002F)\n```\n\nbeats a bare `render(label, true, false)` and beats a comment on the line\nabove, because it can't drift away from the argument it labels.\n\n## What is noise\n\n- Narrating the next line: `\u002F\u002F increment the counter` above `counter += 1`.\n- Section banners: `\u002F\u002F ---- helpers ----`, `\u002F\u002F Validation section`.\n- Restating a name: `\u002F\u002F UserService handles users` on `class UserService`.\n- Comments addressed to the reviewer instead of the next reader: \"fixed the\n  bug here\", \"per feedback\", \"new function to handle retries\", \"changed from\n  the old approach\". These describe the diff, not the code; they are stale\n  the moment the PR merges. If the change history matters, it belongs in the\n  commit message.\n- Comments explaining why your change is correct. Same problem: that is an\n  argument to the reviewer, and it is noise to everyone after.\n\n## Bad, then good\n\n```python\n# Loop through the retries and try the request\nfor attempt in range(5):  # 5 retries\n    resp = fetch(url)\n    if resp.ok:\n        break\n    time.sleep(2 ** attempt)  # exponential backoff\n```\n\n```python\n# Upstream rate-limits bursts; 5 tries with backoff covers their\n# longest observed throttle window (issue #482).\nfor attempt in range(5):\n    resp = fetch(url)\n    if resp.ok:\n        break\n    time.sleep(2 ** attempt)\n```\n\nThree noise comments deleted, one constraint added. The good version has\nfewer comments and more information.\n\n## Docstrings and API docs\n\nA docstring is a contract, not narration: what the function promises\n(arguments, return value, errors raised, side effects, thread-safety), never\nhow the body works. \"Uses a dict internally\" is implementation detail that\nbreaks the doc when the implementation changes. Follow the codebase's\nexisting convention for which symbols get docstrings; a private helper whose\nname says everything doesn't need one just because a linter can count.\n\n## Match the codebase\n\nComment density and idiom are house style like anything else. In a sparsely\ncommented codebase, a fully narrated function is as out of place as a\nreformatted file. Match what surrounds your change: density, tone, doc\ncomment format, tag conventions (`TODO(name):`, `FIXME:`, `# NOTE:`).\n\n## TODOs\n\nA TODO with no owner and no issue link is a wish. Write `TODO(alice): ...`\nor `TODO(#482): ...` so it can be chased, or file the issue and skip the\ncomment. Never leave a TODO describing work the user asked you to finish\nnow.\n\n## Editing existing code\n\n- Remove noise comments in code you are already touching; leave the rest of\n  the file alone. Comment cleanup across untouched code is its own change.\n- Some comments are read by tools, not people: linter and formatter\n  directives (`# noqa`, `eslint-disable-next-line`), coverage pragmas,\n  process tags like ADR references. They say nothing to a reader and are\n  still load-bearing; leave them unless you mean to change what they\n  control.\n- Update any comment your edit makes wrong. A stale comment is worse than\n  none.\n- Never delete a comment stating a constraint you don't understand. It may\n  be the only record of why the code survives production. If it looks wrong,\n  say so to the user instead of removing it.\n",{"name":5,"description":7},"master","b53d3323ad99079621a85542f04a08d04d2dff68","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar","2026-11-10 00:07:15",{"source":8,"skillName":5,"commands":30,"prompt":40,"zipAvailable":41},[31,34,37],{"tool":32,"command":33},"npx","npx skills add gauravjuvekar\u002Fagent-skills --skill code-comments",{"tool":35,"command":36},"bunx","bunx skills add gauravjuvekar\u002Fagent-skills --skill code-comments",{"tool":38,"command":39},"pnpm","pnpm dlx skills add gauravjuvekar\u002Fagent-skills --skill code-comments","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills\u002Fblob\u002Fmaster\u002Fcode-comments\u002FSKILL.md",true,[],[44,51,58,65,73,80],{"skillNo":45,"name":46,"nameZh":6,"description":47,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":48,"categories":49,"keywords":50,"publishedAt":19},"01M7F63A6HBD3DS5QEBBYAS4F5","unslop","Cut AI tells from any writing.","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills\u002Fblob\u002Fmaster\u002Funslop\u002FSKILL.md",[],[],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":19},"01M7F636RBVWKJVNWCZXP7VNT8","sharpen","Sharpen a task before starting: the expert approach, what the user is really after, and the right level of specification. Use for \u002Fsharpen.","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills\u002Fblob\u002Fmaster\u002Fsharpen\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M7F634KB0MT6YP9C3NZVMMMY","read-readmes","Read project README files for context when working in a repository, and change them only when the user explicitly requests README changes.","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills\u002Fblob\u002Fmaster\u002Fread-readmes\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":69,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M7F62Z512PDXHTMR806PSBSG","ponytail","Lazy senior dev mode: the smallest change that fully solves the task, and a reply a busy human understands in one read. Use on any coding task (writing, fixing, refactoring, reviewing, choosing dependencies) and when the user says \"ponytail\", \"be lazy\", \"simplest solution\", \"yagni\", or complains about over-engineering or bloat. Levels: lite, full (default), ultra.","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills\u002Fblob\u002Fmaster\u002Fponytail\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills\u002Fblob\u002Fmaster\u002Fponytail\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7F62VDQT0EXNEQ3T0HAFHZT","nix-for-tools","Use Nix to obtain missing tools or libraries.","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills\u002Fblob\u002Fmaster\u002Fnix-for-tools\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7F62QW1N0FM99PK30JWMKPG","dry-lists","Derive smaller lists or sets from an existing source collection without duplicating its contents. Use when defining a subset of an existing list or set.","https:\u002F\u002Fgithub.com\u002Fgauravjuvekar\u002Fagent-skills\u002Fblob\u002Fmaster\u002Fdry-lists\u002FSKILL.md",[],[]]