[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6WYHTZ780ART10MXTQ7ZABA":3,"skill-same:01M6WYHTZ780ART10MXTQ7ZABA":77},{"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":43,"linkOnly":44,"markdownContent":45,"markdownBody":46,"frontMatter":47,"refName":56,"commitSha":57,"skillDirectory":58,"forksCount":14,"repositoryHtmlUrl":59,"repositoryHomepageUrl":60,"ownerHtmlUrl":61,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":62,"install":63,"resources":76},"01M6WYHTZ780ART10MXTQ7ZABA","documentation",null,"Writing effective project documentation — READMEs, API doc comments, and inline comments that explain why. Use when writing or improving documentation — READMEs, doc comments, inline comments, or when code lacks explanation for non-obvious behavior.","projectious-work\u002Fprocesskit","projectious-work","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F263889726?v=4","01M6N97TJJ118WQ35CHRV8RD0E","projectious.work","01M6N97TPWJPF0BMKYQ4PBY5W8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.13.0\u002Fcontext\u002Fskills\u002Fproduct\u002Fdocumentation\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[5,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"behavior","when","project documentation","api doc","inline","for","v1","comments","project","use","writing","work","explain","why","api","doc","product","code","doc comments","2026-11-10 10:12:30",false,"---\nname: documentation\ndescription: |\n  Writing effective project documentation — READMEs, API doc comments, and inline comments that explain why. Use when writing or improving documentation — READMEs, doc comments, inline comments, or when code lacks explanation for non-obvious behavior.\nmetadata:\n  processkit:\n    apiVersion: processkit.projectious.work\u002Fv1\n    id: SKILL-documentation\n    version: \"1.1.0\"\n    created: 2026-04-06T00:00:00Z\n    category: product\n    layer: 3\n---\n\n# Documentation\n\n## Intro\n\nGood documentation answers the questions a reader actually has:\nwhat is this, how do I use it, why does it work this way. Identify\nthe audience first, then write the smallest doc that serves them.\nDoc comments live with the code; READMEs live with the project.\n\n## Overview\n\n### Identify the audience\n\nDecide before writing whether the reader is a developer integrating\nthe API, an end-user running the tool, or a future maintainer\nreading the source. Each gets a different doc.\n\n### README structure\n\nFor a project README:\n\n1. **What it is** — one sentence\n2. **Quick start** — install command and the first useful command\n3. **Usage examples** — the 2-3 most common cases\n4. **Configuration reference** — flags, env vars, config files\n5. **Contributing guide** — only if open source\n\n### API documentation\n\nEvery public function gets a doc comment. Include:\n\n- What it does (one sentence)\n- Parameters\n- Return value\n- Errors or panics\n- A short usage example for non-obvious APIs\n\n### Inline comments\n\nUse inline comments sparingly:\n\n- Comment **why**, not **what** — the code shows the what.\n- Document non-obvious business rules.\n- Explain workarounds with links to issues or specs.\n- Never comment out code — delete it. Git remembers.\n\n### Locality\n\nKeep docs close to code. Doc comments beat wiki pages beat\nexternal sites. The further docs travel from the code, the faster\nthey go stale.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Writing docs before identifying the audience.** Documentation for a developer integrating an API is completely different from documentation for a user running a tool. Write the wrong one and it helps nobody. Identify the reader before writing the first word.\n- **Restating the code in comments.** `# increments i` next to `i += 1` adds noise, not signal. Comments explain why — the business rule, the workaround, the non-obvious constraint — not what, which the code already shows.\n- **Tutorial-as-README.** A README is a map, not a textbook. A 3,000-word introductory walkthrough in the README buries the quick start. Link to a tutorial; don't inline it.\n- **TODO comments without owners or dates.** A TODO without an owner and a deadline becomes permanent infrastructure. Either fix it immediately, file a ticket and link it, or delete the TODO.\n- **Stale comments that contradict the code.** A comment that says one thing while the code does another is actively harmful — it misdirects the reader. Update or delete comments on every change that touches the relevant code.\n- **Undocumented public API.** Every exported symbol is a promise. If a function is worth exporting, it's worth a doc comment that explains what it does, its parameters, its return value, and any surprising behavior.\n- **Docs stored far from the code.** Wiki pages and external sites go stale because the friction of updating them is higher than the friction of updating the code. Keep docs close to code; doc comments beat wikis.\n\n## Full reference\n\n### Example doc comment\n\n```rust\n\u002F\u002F\u002F Calculates the shipping cost based on weight and destination zone.\n\u002F\u002F\u002F\n\u002F\u002F\u002F Returns `None` if the destination zone is not serviceable.\n\u002F\u002F\u002F Weights over 30kg use freight pricing instead.\n```\n\nThe example is short, names the inputs and outputs, and surfaces\nthe two non-obvious rules (unservicable zones return `None`,\nheavy items switch to freight).\n\n### Anti-patterns\n\n- **Restating the code** — `\u002F\u002F increments i` next to `i += 1`.\n- **Stale comments** — comments that contradict the code are\n  worse than no comments. Delete or update them on every change.\n- **Tutorial-as-README** — a README is a map, not a textbook.\n  Link to the tutorial; don't inline it.\n- **Undocumented public API** — every exported symbol is a\n  promise. If it's worth exporting, it's worth a doc comment.\n- **TODO comments without owners or dates** — they rot. Either\n  fix it or file a ticket and link the ticket id.\n\n### When to write less\n\nA function with a self-evident name and a short body usually\nneeds no doc comment. Save the words for the parts where the\nreader might be surprised.\n","# Documentation\n\n## Intro\n\nGood documentation answers the questions a reader actually has:\nwhat is this, how do I use it, why does it work this way. Identify\nthe audience first, then write the smallest doc that serves them.\nDoc comments live with the code; READMEs live with the project.\n\n## Overview\n\n### Identify the audience\n\nDecide before writing whether the reader is a developer integrating\nthe API, an end-user running the tool, or a future maintainer\nreading the source. Each gets a different doc.\n\n### README structure\n\nFor a project README:\n\n1. **What it is** — one sentence\n2. **Quick start** — install command and the first useful command\n3. **Usage examples** — the 2-3 most common cases\n4. **Configuration reference** — flags, env vars, config files\n5. **Contributing guide** — only if open source\n\n### API documentation\n\nEvery public function gets a doc comment. Include:\n\n- What it does (one sentence)\n- Parameters\n- Return value\n- Errors or panics\n- A short usage example for non-obvious APIs\n\n### Inline comments\n\nUse inline comments sparingly:\n\n- Comment **why**, not **what** — the code shows the what.\n- Document non-obvious business rules.\n- Explain workarounds with links to issues or specs.\n- Never comment out code — delete it. Git remembers.\n\n### Locality\n\nKeep docs close to code. Doc comments beat wiki pages beat\nexternal sites. The further docs travel from the code, the faster\nthey go stale.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Writing docs before identifying the audience.** Documentation for a developer integrating an API is completely different from documentation for a user running a tool. Write the wrong one and it helps nobody. Identify the reader before writing the first word.\n- **Restating the code in comments.** `# increments i` next to `i += 1` adds noise, not signal. Comments explain why — the business rule, the workaround, the non-obvious constraint — not what, which the code already shows.\n- **Tutorial-as-README.** A README is a map, not a textbook. A 3,000-word introductory walkthrough in the README buries the quick start. Link to a tutorial; don't inline it.\n- **TODO comments without owners or dates.** A TODO without an owner and a deadline becomes permanent infrastructure. Either fix it immediately, file a ticket and link it, or delete the TODO.\n- **Stale comments that contradict the code.** A comment that says one thing while the code does another is actively harmful — it misdirects the reader. Update or delete comments on every change that touches the relevant code.\n- **Undocumented public API.** Every exported symbol is a promise. If a function is worth exporting, it's worth a doc comment that explains what it does, its parameters, its return value, and any surprising behavior.\n- **Docs stored far from the code.** Wiki pages and external sites go stale because the friction of updating them is higher than the friction of updating the code. Keep docs close to code; doc comments beat wikis.\n\n## Full reference\n\n### Example doc comment\n\n```rust\n\u002F\u002F\u002F Calculates the shipping cost based on weight and destination zone.\n\u002F\u002F\u002F\n\u002F\u002F\u002F Returns `None` if the destination zone is not serviceable.\n\u002F\u002F\u002F Weights over 30kg use freight pricing instead.\n```\n\nThe example is short, names the inputs and outputs, and surfaces\nthe two non-obvious rules (unservicable zones return `None`,\nheavy items switch to freight).\n\n### Anti-patterns\n\n- **Restating the code** — `\u002F\u002F increments i` next to `i += 1`.\n- **Stale comments** — comments that contradict the code are\n  worse than no comments. Delete or update them on every change.\n- **Tutorial-as-README** — a README is a map, not a textbook.\n  Link to the tutorial; don't inline it.\n- **Undocumented public API** — every exported symbol is a\n  promise. If it's worth exporting, it's worth a doc comment.\n- **TODO comments without owners or dates** — they rot. Either\n  fix it or file a ticket and link the ticket id.\n\n### When to write less\n\nA function with a self-evident name and a short body usually\nneeds no doc comment. Save the words for the parts where the\nreader might be surprised.\n",{"name":5,"metadata":48,"description":55},{"processkit":49},{"id":50,"layer":51,"created":52,"version":53,"category":40,"apiVersion":54},"SKILL-documentation",3,1775433600000,"1.1.0","processkit.projectious.work\u002Fv1","Writing effective project documentation — READMEs, API doc comments, and inline comments that explain why. Use when writing or improving documentation — READMEs, doc comments, inline comments, or when code lacks explanation for non-obvious behavior.\n","main","4876a92620ee792aac2ac9a1a806322d8a572367","archive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.13.0\u002Fcontext\u002Fskills\u002Fproduct\u002Fdocumentation","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit","https:\u002F\u002Fprojectious-work.github.io\u002Fprocesskit\u002F","https:\u002F\u002Fgithub.com\u002Fprojectious-work","2026-11-09 00:53:29",{"source":8,"skillName":5,"commands":64,"prompt":74,"zipAvailable":75},[65,68,71],{"tool":66,"command":67},"npx","npx skills add projectious-work\u002Fprocesskit --skill documentation",{"tool":69,"command":70},"bunx","bunx skills add projectious-work\u002Fprocesskit --skill documentation",{"tool":72,"command":73},"pnpm","pnpm dlx skills add projectious-work\u002Fprocesskit --skill documentation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.13.0\u002Fcontext\u002Fskills\u002Fproduct\u002Fdocumentation\u002FSKILL.md",true,[],[78,104,124,145,162,180],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":89,"publishedAt":43},"01M6X5MTC89B4ZGXW3JVSQCPF8","skill-management","Manage Skill package manifests as v1 ontology entities.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fskill-management\u002FSKILL.md",[84],{"categoryNo":85,"categoryName":86,"taxonomyType":87,"taxonomyTypeDesc":88},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[90,91,92,93,94,95,35,96,97,98,80,99,100,101,30,102,103],"management","skill management","create","update","package","alpha","list","manage","ontology","get","as","manifests","skill package","transition",{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":111,"publishedAt":43},"01M6X5MCV74NHW5MEDNHZRF2C8","schema-management","Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fschema-management\u002FSKILL.md",[110],{"categoryNo":85,"categoryName":86,"taxonomyType":87,"taxonomyTypeDesc":88},[90,112,113,114,115,116,95,35,117,118,97,119,120,121,99,122,123],"schema","schema management","MCP","workflows","validation","generated","rebuild","contracts","wed","deterministic","contract","mode",{"skillNo":125,"name":126,"nameZh":6,"description":127,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":128,"categories":129,"keywords":130,"publishedAt":43},"01M6X5M5G6YJ96AMZGSCZJ1D13","proposition-management","Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fproposition-management\u002FSKILL.md",[],[90,131,132,92,93,133,95,35,134,135,136,137,99,138,139,140,141,142,143,144],"proposition","proposition management","index","log","world","record","query","creation","event","interface","updates","facts","claims","WSJF",{"skillNo":146,"name":147,"nameZh":6,"description":148,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":149,"categories":150,"keywords":151,"publishedAt":43},"01M6X5KMQ83QN9M6MPWZM7344F","ontology-management","Manage generated v1 ontology entities that do not require a dedicated domain server.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fontology-management\u002FSKILL.md",[],[90,98,152,92,95,153,154,117,155,134,97,156,157,99,158,159,139,160,30,161],"ontology management","lifecycle","archive","roadmap","do","domain","iteration","keep","measurement","generic",{"skillNo":163,"name":164,"nameZh":6,"description":165,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":166,"categories":167,"keywords":168,"publishedAt":43},"01M6X5KCY2DN3SM21RERSFNEBT","okf-compatibility","Import, export, and validate conformant Open Knowledge Format bundles.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fokf-compatibility\u002FSKILL.md",[],[169,170,171,172,95,173,174,175,35,176,177,178,179],"okf","compatibility","okf compatibility","validate","open","knowledge","format","export","bundles","bundle","import",{"skillNo":181,"name":182,"nameZh":6,"description":183,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":184,"categories":185,"keywords":186,"publishedAt":43},"01M6X5JA8S5PNGJVFW4EQY8T83","capability-management","Manage versioned Capability entities and their governed lifecycle.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fcapability-management\u002FSKILL.md",[],[90,187,188,92,93,133,95,153,35,96,134,189,97,136,99,159,139,140,190,103],"capability","capability management","queries","changes"]