[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7B3ETHKDG7DETF84R7NBE0Q":3,"skill-same:01M7B3ETHKDG7DETF84R7NBE0Q":45},{"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":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":27,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M7B3ETHKDG7DETF84R7NBE0Q","vvkit-writing-comments",null,"Use when writing or reviewing comments and doc comments, or when a diff adds explanatory prose alongside code.","vadimvitvickiy\u002Fvv-agent-kit","vadimvitvickiy","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F5019512?v=4","01M7B3ABRYF7KHBCDW6GB2XH0C","Vadim Vitvitskii","01M7B3ABSZYG9MXP1CC7BQYM25",0,"MIT","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fcodex\u002Fplugins\u002Fvvkit\u002Fskills\u002Fvvkit-writing-comments\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: vvkit-writing-comments\ndescription: \"Use when writing or reviewing comments and doc comments, or when a diff adds explanatory prose alongside code.\"\n---\n\n# Writing comments\n\n**The default is no comment.** Names and structure carry the meaning; a comment is for what they\nprovably cannot. Where the project has a convention, follow the project.\n\n## Codex runtime\n\nLoad referenced skills by reading their SKILL.md. Surveyor, reviewer and runner\nskills are role instructions, not registered agent types or enforced tool allowlists.\nUse a generic subagent only when delegation is available and permitted; otherwise\nperform the role inline. Follow the active session's model, context and permission\nrules. User authorization takes precedence over imported workflow approval gates.\nClaude hooks and plugin commands are not active in this package. Existing\n`.claude\u002Fcontext\u002F` paths refer to project documents, not Codex configuration.\n\n## The one test\n\n- A comment answers **why**, and the why is not obvious from the code beside it.\n- Describes *what* the code does: delete it. Recoverable from the next three lines: delete it.\n- Code that needs a comment to be followed needs a better name or a smaller function instead.\n\n## Limits\n\n| Kind | Limit |\n|-|-|\n| Line comment | **1 line** |\n| Member doc comment (function, property, case) | **1 line.** A second only for a genuinely subtle exception |\n| Type-level doc comment (class, struct, enum, protocol, module) | Several lines, to orient a reader about the whole type |\n\nOver the limit means **cut, not reflow** — the second sentence usually restates the first.\n\n## Never\n\n- **Narrate** — \"loop over the items\", \"set the title\", \"returns nil when empty\".\n- **Restate the signature** — a parameter doc repeating the name and type.\n- **Decorative dividers.** A structured section marker the language supports is fine.\n- **Migration history** — \"moved from X\", \"new in the refactor\". Git knows.\n- **Ticket ids.** In public API docs they leak an internal tracker.\n- **Commentary on the change.** Describe the code as it stands, not how it got there.\n\n## When a doc comment is warranted\n\n| Declaration | Doc comment |\n|-|-|\n| Public or exported | **Yes** — it is the contract, and exempt from the member limit where the contract needs the words |\n| Internal helper with a non-obvious exception | Yes — one line naming the exception |\n| Internal helper self-evident from its name | No |\n| Override or conformance with no added behavior | No |\n| A constant whose value encodes a decision | Yes — why *this* value |\n\n## Existing comments\n\n- **Never delete an existing comment or TODO** unless asked. These rules govern what you write, not\n  what you remove.\n- **Never overwrite an existing doc comment.** Add where missing; reconcile only when the contract\n  changed.\n\n## Self-check\n\nEvery multi-line comment block you just added:\n\n```bash\ngit diff -U0 | awk '\u002F^\\+ *(\\\u002F\\\u002F|#|--)\u002F{n++; if (n>1) print; next} {n=0}'\n```\n\nEmpty output, or only type-level overviews, passes. Anything else is over the limit until you can\nname why that block earns a second line.\n","# Writing comments\n\n**The default is no comment.** Names and structure carry the meaning; a comment is for what they\nprovably cannot. Where the project has a convention, follow the project.\n\n## Codex runtime\n\nLoad referenced skills by reading their SKILL.md. Surveyor, reviewer and runner\nskills are role instructions, not registered agent types or enforced tool allowlists.\nUse a generic subagent only when delegation is available and permitted; otherwise\nperform the role inline. Follow the active session's model, context and permission\nrules. User authorization takes precedence over imported workflow approval gates.\nClaude hooks and plugin commands are not active in this package. Existing\n`.claude\u002Fcontext\u002F` paths refer to project documents, not Codex configuration.\n\n## The one test\n\n- A comment answers **why**, and the why is not obvious from the code beside it.\n- Describes *what* the code does: delete it. Recoverable from the next three lines: delete it.\n- Code that needs a comment to be followed needs a better name or a smaller function instead.\n\n## Limits\n\n| Kind | Limit |\n|-|-|\n| Line comment | **1 line** |\n| Member doc comment (function, property, case) | **1 line.** A second only for a genuinely subtle exception |\n| Type-level doc comment (class, struct, enum, protocol, module) | Several lines, to orient a reader about the whole type |\n\nOver the limit means **cut, not reflow** — the second sentence usually restates the first.\n\n## Never\n\n- **Narrate** — \"loop over the items\", \"set the title\", \"returns nil when empty\".\n- **Restate the signature** — a parameter doc repeating the name and type.\n- **Decorative dividers.** A structured section marker the language supports is fine.\n- **Migration history** — \"moved from X\", \"new in the refactor\". Git knows.\n- **Ticket ids.** In public API docs they leak an internal tracker.\n- **Commentary on the change.** Describe the code as it stands, not how it got there.\n\n## When a doc comment is warranted\n\n| Declaration | Doc comment |\n|-|-|\n| Public or exported | **Yes** — it is the contract, and exempt from the member limit where the contract needs the words |\n| Internal helper with a non-obvious exception | Yes — one line naming the exception |\n| Internal helper self-evident from its name | No |\n| Override or conformance with no added behavior | No |\n| A constant whose value encodes a decision | Yes — why *this* value |\n\n## Existing comments\n\n- **Never delete an existing comment or TODO** unless asked. These rules govern what you write, not\n  what you remove.\n- **Never overwrite an existing doc comment.** Add where missing; reconcile only when the contract\n  changed.\n\n## Self-check\n\nEvery multi-line comment block you just added:\n\n```bash\ngit diff -U0 | awk '\u002F^\\+ *(\\\u002F\\\u002F|#|--)\u002F{n++; if (n>1) print; next} {n=0}'\n```\n\nEmpty output, or only type-level overviews, passes. Anything else is over the limit until you can\nname why that block earns a second line.\n",{"name":5,"description":7},"main","cc22a222a76add5759a2df5fadf231a758691db5","codex\u002Fplugins\u002Fvvkit\u002Fskills\u002Fvvkit-writing-comments","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy","Senior iOS engineer. Architecture, SDKs and apps for iOS, tvOS and watchOS.","2026-11-13 19:10:29",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add vadimvitvickiy\u002Fvv-agent-kit --skill vvkit-writing-comments",{"tool":37,"command":38},"bunx","bunx skills add vadimvitvickiy\u002Fvv-agent-kit --skill vvkit-writing-comments",{"tool":40,"command":41},"pnpm","pnpm dlx skills add vadimvitvickiy\u002Fvv-agent-kit --skill vvkit-writing-comments","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fcodex\u002Fplugins\u002Fvvkit\u002Fskills\u002Fvvkit-writing-comments\u002FSKILL.md",true,[],[46,53,60,67,74,81],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":19},"01M7B3JN7VG0YJ4JB8RP6HYZSJ","no-heading","Use when proving that the validator rejects a body with no H1 and a force-loading @-link.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fno-heading\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M7B3JJMEW4E710ZG6HYJ7BWV","wrong-name-does-not-match-dir","Dispatches a subagent per task and reviews between each one.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Fskills\u002Fbroken-skill\u002FSKILL.md",[],[],{"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":19},"01M7B3JGE9MFT1HRP41YRVKN97","writing-tests","Use when adding or changing behavior, fixing a bug, or judging whether an existing or generated test earns its place.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-tests\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M7B3JD5X32VEBDBN7HB8E17Z","writing-skills","Use when authoring or editing a skill, agent, command or hook for this kit, or when deciding whether a piece of guidance belongs in a skill at all.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-skills\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7B3J992MZH2QVZRED0DRPD9","writing-project-instructions","Use when creating or editing a CLAUDE.md or AGENTS.md, when it has grown long, or when a rule in it also exists in an installed skill.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-project-instructions\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7B3J55C5WPWN20QXP9ET848","writing-logs","Use when adding or reviewing log statements, or when deciding what level a message belongs at.","https:\u002F\u002Fgithub.com\u002Fvadimvitvickiy\u002Fvv-agent-kit\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-logs\u002FSKILL.md",[],[]]