[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6BVCGD4V5B7R4BCS8NGQEE8":3,"skill-same:01M6BVCGD4V5B7R4BCS8NGQEE8":59},{"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":23,"publishedAt":32,"linkOnly":33,"markdownContent":34,"markdownBody":35,"frontMatter":36,"refName":37,"commitSha":38,"skillDirectory":39,"forksCount":40,"repositoryHtmlUrl":41,"repositoryHomepageUrl":6,"ownerHtmlUrl":42,"ownerBlogUrl":43,"ownerDescription":6,"updatedAt":44,"install":45,"resources":58},"01M6BVCGD4V5B7R4BCS8NGQEE8","code-comments",null,"Write code comments that comment the non-obvious and delete the rest. Use when writing or editing comments in source code, adding explanatory comments to a change, or when the user asks to add, trim, or review comments. Steers toward brief, intent-focused comments and away from backstory, justification, or restating the code.","SamFleming\u002Fdotfiles","SamFleming","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F573318?v=4","01M6BVCCB0H1C12FM8T54ZH5R4","Sam Fleming","01M6BVCCF0G9K0TXCYZ894P432",2,"MIT","https:\u002F\u002Fgithub.com\u002FSamFleming\u002Fdotfiles\u002Fblob\u002Fmaster\u002Fhome\u002Fclaude\u002F.claude\u002Fskills\u002Fcode-comments\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[24,25,26,27,28,29,30,31],"code","code comments","writing","review","change","delete","brief","REST","2026-11-10 10:12:30",false,"---\nname: code-comments\ndescription: \"Write code comments that comment the non-obvious and delete the rest. Use when writing or editing comments in source code, adding explanatory comments to a change, or when the user asks to add, trim, or review comments. Steers toward brief, intent-focused comments and away from backstory, justification, or restating the code.\"\n---\n\n# Code comments\n\nComment the non-obvious; delete the rest. A comment is a cost (it rots, it adds noise); it has to buy more than it costs.\n\n## A comment earns its place only if it says something the code can't\n- Intent that isn't visible in the code itself\n- A non-obvious decision or trade-off: *why here, why this way, not the obvious alternative*\n- A constraint, invariant, or gotcha that will bite a later editor\n- A pointer to context the reader needs (spec, ticket) as a link, not a retelling\n\n## Never\n- Restate what the code plainly does (`\u002F\u002F increment i`) or echo the function\u002Fvariable name\n- Narrate the backstory or justify the change: what was broken, what you investigated, why it matters. That's PR \u002F commit \u002F ticket territory, not source.\n- Leave a comment the next edit will quietly make false\n\n## The test\nBefore keeping a comment, ask: **does this describe what the code does or why it's here, or is it justifying the change \u002F telling a story?** A story or a justification gets cut, or moved to the commit or PR.\n\n## Style\n- Usually one line. Say the thing and stop.\n- Match the file's existing comment density and idiom; don't import a different house style.\n- Prefer *why* over *what*. The what is in the code and rots fast; the why rots slowly.\n- Rich context (root cause, the investigation, environment-specific findings) belongs in the PR, ticket, or commit message, not the source.\n\n## Worked example: trim to the one non-obvious fact\n\nA `collectDefaultMetrics()` call added to a shared metrics module:\n\n```\nv1 (7 lines): full backstory — idle process serves empty \u002Fmetrics, looks\n              identical to a broken endpoint, makes the partner metric a\n              clean signal…                                    → an essay\nv2 (2 lines): \"…so an idle process still exposes a non-empty \u002Fmetrics;\n              every other metric here is labelled…\"            → still justifying the change\nv3 (1 line):  \"Here, not per-app, so every app importing these metrics\n              also gets the process_*\u002Fnodejs_* baseline.\"      → the one non-obvious fact: placement\n```\n\nEach trim drops a layer of justification until only the thing a reader can't infer from the code remains: *why the call lives in this shared module*.\n","# Code comments\n\nComment the non-obvious; delete the rest. A comment is a cost (it rots, it adds noise); it has to buy more than it costs.\n\n## A comment earns its place only if it says something the code can't\n- Intent that isn't visible in the code itself\n- A non-obvious decision or trade-off: *why here, why this way, not the obvious alternative*\n- A constraint, invariant, or gotcha that will bite a later editor\n- A pointer to context the reader needs (spec, ticket) as a link, not a retelling\n\n## Never\n- Restate what the code plainly does (`\u002F\u002F increment i`) or echo the function\u002Fvariable name\n- Narrate the backstory or justify the change: what was broken, what you investigated, why it matters. That's PR \u002F commit \u002F ticket territory, not source.\n- Leave a comment the next edit will quietly make false\n\n## The test\nBefore keeping a comment, ask: **does this describe what the code does or why it's here, or is it justifying the change \u002F telling a story?** A story or a justification gets cut, or moved to the commit or PR.\n\n## Style\n- Usually one line. Say the thing and stop.\n- Match the file's existing comment density and idiom; don't import a different house style.\n- Prefer *why* over *what*. The what is in the code and rots fast; the why rots slowly.\n- Rich context (root cause, the investigation, environment-specific findings) belongs in the PR, ticket, or commit message, not the source.\n\n## Worked example: trim to the one non-obvious fact\n\nA `collectDefaultMetrics()` call added to a shared metrics module:\n\n```\nv1 (7 lines): full backstory — idle process serves empty \u002Fmetrics, looks\n              identical to a broken endpoint, makes the partner metric a\n              clean signal…                                    → an essay\nv2 (2 lines): \"…so an idle process still exposes a non-empty \u002Fmetrics;\n              every other metric here is labelled…\"            → still justifying the change\nv3 (1 line):  \"Here, not per-app, so every app importing these metrics\n              also gets the process_*\u002Fnodejs_* baseline.\"      → the one non-obvious fact: placement\n```\n\nEach trim drops a layer of justification until only the thing a reader can't infer from the code remains: *why the call lives in this shared module*.\n",{"name":5,"description":7},"master","dc8003d37a723360f1d73b2889ca447ff4a16844","home\u002Fclaude\u002F.claude\u002Fskills\u002Fcode-comments",1,"https:\u002F\u002Fgithub.com\u002FSamFleming\u002Fdotfiles","https:\u002F\u002Fgithub.com\u002FSamFleming","samfleming.me","2026-10-26 07:52:31",{"source":8,"skillName":5,"commands":46,"prompt":56,"zipAvailable":57},[47,50,53],{"tool":48,"command":49},"npx","npx skills add SamFleming\u002Fdotfiles --skill code-comments",{"tool":51,"command":52},"bunx","bunx skills add SamFleming\u002Fdotfiles --skill code-comments",{"tool":54,"command":55},"pnpm","pnpm dlx skills add SamFleming\u002Fdotfiles --skill code-comments","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSamFleming\u002Fdotfiles\u002Fblob\u002Fmaster\u002Fhome\u002Fclaude\u002F.claude\u002Fskills\u002Fcode-comments\u002FSKILL.md",true,[],[60,69,82,98,105,113],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":32},"01M6BVCYMF5PJ3GTNS7477TNVB","zoom-out","Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.","https:\u002F\u002Fgithub.com\u002FSamFleming\u002Fdotfiles\u002Fblob\u002Fmaster\u002Fhome\u002Fclaude\u002F.claude\u002Fskills\u002Fzoom-out\u002FSKILL.md",[],[67,24,68],"zoom out","how",{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":32},"01M6BVCWXARRXMPJEA3R0J1Y0D","tdd","Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions \"red-green-refactor\", or wants integration tests.","https:\u002F\u002Fgithub.com\u002FSamFleming\u002Fdotfiles\u002Fblob\u002Fmaster\u002Fhome\u002Fclaude\u002F.claude\u002Fskills\u002Ftdd\u002FSKILL.md",[],[71,76,77,78,79,80,81],"test","integration tests","development","integration","refactor","first",{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":93,"publishedAt":32},"01M6BVCVC4JQ7PFX29NS7N20E1","improve-codebase-architecture","Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.","https:\u002F\u002Fgithub.com\u002FSamFleming\u002Fdotfiles\u002Fblob\u002Fmaster\u002Fhome\u002Fclaude\u002F.claude\u002Fskills\u002Fimprove-codebase-architecture\u002FSKILL.md",[88],{"categoryNo":89,"categoryName":90,"taxonomyType":91,"taxonomyTypeDesc":92},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",[94,95,96,97],"improve","architecture","improve codebase architecture","report",{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":32},"01M6BVCT2AD4MTJ3GENDX15XMS","handoff","Compact the current conversation into a handoff document for another agent to pick up.","https:\u002F\u002Fgithub.com\u002FSamFleming\u002Fdotfiles\u002Fblob\u002Fmaster\u002Fhome\u002Fclaude\u002F.claude\u002Fskills\u002Fhandoff\u002FSKILL.md",[],[100],{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":111,"publishedAt":32},"01M6BVCRZMCZYCK99DZKV81YFB","grilling","Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.","https:\u002F\u002Fgithub.com\u002FSamFleming\u002Fdotfiles\u002Fblob\u002Fmaster\u002Fhome\u002Fclaude\u002F.claude\u002Fskills\u002Fgrilling\u002FSKILL.md",[],[107,112,76],"plan",{"skillNo":114,"name":115,"nameZh":6,"description":116,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":117,"categories":118,"keywords":119,"publishedAt":32},"01M6BVCQCMATEZ7Z7WWFTGMJSH","grill-with-docs","A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.","https:\u002F\u002Fgithub.com\u002FSamFleming\u002Fdotfiles\u002Fblob\u002Fmaster\u002Fhome\u002Fclaude\u002F.claude\u002Fskills\u002Fgrill-with-docs\u002FSKILL.md",[],[120,121,112,122,123],"docs","grill with docs","go","design"]