[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6NQTV5QRKJ97T2RBNHT836R":3,"skill-same:01M6NQTV5QRKJ97T2RBNHT836R":80},{"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":41,"linkOnly":42,"markdownContent":43,"markdownBody":44,"frontMatter":45,"refName":54,"commitSha":55,"skillDirectory":56,"forksCount":14,"repositoryHtmlUrl":57,"repositoryHomepageUrl":58,"ownerHtmlUrl":59,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":60,"install":61,"resources":74},"01M6NQTV5QRKJ97T2RBNHT836R","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\u002Fsrc\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],"work","project documentation","api doc","inline","for","comments","project","use","behavior","writing","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\u002Fv2\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":46,"description":53},{"processkit":47},{"id":48,"layer":49,"created":50,"version":51,"category":38,"apiVersion":52},"SKILL-documentation",3,1775433600000,"1.1.0","processkit.projectious.work\u002Fv2","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","7231f100e266e30d2c1699ecde5c00602471dc3c","src\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-11 23:24:18",{"source":8,"skillName":5,"commands":62,"prompt":72,"zipAvailable":73},[63,66,69],{"tool":64,"command":65},"npx","npx skills add projectious-work\u002Fprocesskit --skill documentation",{"tool":67,"command":68},"bunx","bunx skills add projectious-work\u002Fprocesskit --skill documentation",{"tool":70,"command":71},"pnpm","pnpm dlx skills add projectious-work\u002Fprocesskit --skill documentation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fproduct\u002Fdocumentation\u002FSKILL.md",true,[75],{"path":76,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":14,"sourceHtmlUrl":79},"scripts\u002F.gitkeep","SCRIPT","脚本","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fproduct\u002Fdocumentation\u002Fscripts\u002F.gitkeep",[81,88,95,101,128,148],{"skillNo":82,"name":83,"nameZh":6,"description":6,"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":87},"01M7665G2ED3624R3X93304265","standard-ui-design","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-ui-design\u002FSKILL.md",[],[],"2026-11-12 13:55:43",{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":87},"01M76651QTC6W0HJ4AFW2MMR3V","standard-agent-use","Company standard for working with AI agents. Use when deciding what to delegate to agents, capturing open work, keeping agent memory or knowledge notes, improving an agent workflow, or introducing agent work in a team or for a client.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-use\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":87},"01M76650NN4T8P241021NBR64S","standard-agent-building","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstandard-agent-building\u002FSKILL.md",[],[],{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":112,"publishedAt":41},"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",[107],{"categoryNo":108,"categoryName":109,"taxonomyType":110,"taxonomyTypeDesc":111},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[113,114,115,116,117,118,24,119,120,121,122,123,103,124,125,126,127],"management","skill management","ontology","v1","create","as","transition","get","manage","update","alpha","list","package","skill package","manifests",{"skillNo":129,"name":130,"nameZh":6,"description":131,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":132,"categories":133,"keywords":135,"publishedAt":41},"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",[134],{"categoryNo":108,"categoryName":109,"taxonomyType":110,"taxonomyTypeDesc":111},[136,137,113,138,139,140,141,142,143,144,145,146,24,120,121,123,147],"schema","schema management","contract","rebuild","contracts","workflows","wed","generated","MCP","validation","deterministic","mode",{"skillNo":149,"name":150,"nameZh":6,"description":151,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":152,"categories":153,"keywords":154,"publishedAt":41},"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",[],[155,113,156,157,117,158,159,160,24,120,161,162,122,163,123,164,165,166,167,168],"proposition management","proposition","interface","claims","record","world","creation","event","WSJF","index","updates","query","facts","log"]