[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72S8PVW4W2WCKADRVJKEYWQ":3,"skill-same:01M72S8PVW4W2WCKADRVJKEYWQ":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M72S8PVW4W2WCKADRVJKEYWQ","fsdocs-api-doc",null,"This skill should be used when the user asks to \"add doc comments\", \"improve XML docs\", \"document the API\", \"add XML documentation\", \"write doc comments for F#\", \"document public API\", \"add summary comments\", or needs to write or improve `\u002F\u002F\u002F` XML documentation comments in F# source files. This skill edits .fs source files, not docs\u002F content files.","EHotwagner\u002FFS-Skia-UI","EHotwagner","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1645484?v=4","01M72S7CTBDPQDQHQJKKHY87K9","01M72S7CVFD0JN82RVX21NFEVC",2,"MIT","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Ffsdocs-api-doc\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: fsdocs-api-doc\ndescription: This skill should be used when the user asks to \"add doc comments\", \"improve XML docs\", \"document the API\", \"add XML documentation\", \"write doc comments for F#\", \"document public API\", \"add summary comments\", or needs to write or improve `\u002F\u002F\u002F` XML documentation comments in F# source files. This skill edits .fs source files, not docs\u002F content files.\nversion: 0.1.0\n---\n\n# Improve XML Doc Comments in F# Source Files\n\nAdd and improve `\u002F\u002F\u002F` XML documentation comments in F# source files so FSharp.Formatting generates high-quality API reference pages.\n\n**Key capabilities:**\n- Audit public API surface for missing or low-quality doc comments\n- Write idiomatic F# XML doc comments with proper tag usage\n- Document F#-specific constructs: discriminated unions, computation expressions, active patterns\n- Add namespace-level documentation via sentinel modules\n- Organize API docs with categories\n\n## Overview\n\nFSharp.Formatting generates API reference pages from compiled assemblies and their XML documentation files. The quality of these pages depends entirely on the `\u002F\u002F\u002F` comments in source code. This skill focuses on editing `.fs` source files to improve those comments — it does not create files in `docs\u002F`.\n\nEnsure `\u003CGenerateDocumentationFile>true\u003C\u002FGenerateDocumentationFile>` is set in project properties before starting. Without this, the compiler does not emit XML doc files.\n\n## Workflow\n\n### 1. Build to Verify Compilation\n\nBuild the project first to confirm it compiles cleanly:\n\n```\ndotnet build -c Release\n```\n\nFix any compilation errors before documenting. Documentation work requires a compilable codebase.\n\n### 2. Identify Public API Surface\n\nScan for all public declarations that will appear in generated API docs:\n- Modules and their public functions\u002Fvalues\n- Types (records, DUs, classes) and their members\n- Type extensions\n- Active patterns\n- Computation expression builders\n\nFocus on items visible to library consumers. Internal or private members do not appear in standard API docs.\n\nPrioritize by impact: types and functions that most users will encounter first deserve the best documentation. Start with the main entry points and work outward.\n\n### 3. Audit Existing Documentation\n\nFor each public API member, check:\n- Is there a `\u003Csummary>` at minimum?\n- Do functions with parameters have `\u003Cparam>` tags?\n- Do functions returning non-obvious types have `\u003Creturns>` tags?\n- Are there `\u003Cexample>` blocks for non-trivial usage?\n- Are discriminated union cases individually documented?\n\n### 4. Write XML Doc Comments\n\nApply `\u002F\u002F\u002F` comments to all public members. Follow the tag priority:\n\n**Essential (every public member):**\n- `\u003Csummary>` — one to three sentences describing purpose and behavior\n\n**Important (when applicable):**\n- `\u003Cparam name=\"x\">` — describe each parameter's purpose and constraints\n- `\u003Creturns>` — describe return value, especially for non-obvious types\n- `\u003Cexample>` — show typical usage with a code block\n- `\u003Cremarks>` — additional context, algorithms, performance notes\n\n**Supplemental:**\n- `\u003Cexception cref=\"T:System.ArgumentException\">` — document thrown exceptions\n- `\u003Csee cref=\"T:Namespace.Type\"\u002F>` — cross-reference related types\n- `\u003Cseealso cref=\"T:Namespace.Type\"\u002F>` — related reading\n- `\u003Ctypeparam name=\"'a\">` — describe generic type parameters\n\n### 5. Add Namespace Documentation\n\nCreate a sentinel module for each namespace to provide namespace-level docs:\n\n```fsharp\nnamespace MyLib.Core\n\n\u002F\u002F\u002F \u003Cnamespacedoc>\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Core types and functions for MyLib. Contains the primary domain\n\u002F\u002F\u002F model and essential operations.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n\u002F\u002F\u002F \u003C\u002Fnamespacedoc>\nmodule internal NamespaceDoc = ()\n```\n\nPlace this at the top of the first file in each namespace. The module must be `internal` — it exists only to carry the `\u003Cnamespacedoc>` tag.\n\n### 6. Organize with Categories\n\nGroup related members using `\u003Ccategory>` tags on types and modules:\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>String manipulation utilities.\u003C\u002Fsummary>\n\u002F\u002F\u002F \u003Ccategory>Text Processing\u003C\u002Fcategory>\nmodule StringOps =\n    \u002F\u002F ...\n```\n\nCategories create groupings on the namespace page, making large APIs navigable.\n\n### 7. Build and Verify\n\nBuild the documentation to verify comments render correctly:\n\n```\ndotnet fsdocs build --clean\n```\n\nCheck the generated API pages in `output\u002Freference\u002F` for formatting issues, broken cross-references, and missing content.\n\n## Quick Reference: Common Tags\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>Brief description of the member.\u003C\u002Fsummary>\n\u002F\u002F\u002F \u003Cparam name=\"input\">Description of the parameter.\u003C\u002Fparam>\n\u002F\u002F\u002F \u003Creturns>Description of the return value.\u003C\u002Freturns>\n\u002F\u002F\u002F \u003Cexample>\n\u002F\u002F\u002F \u003Ccode>\n\u002F\u002F\u002F let result = MyModule.transform \"hello\"\n\u002F\u002F\u002F \u002F\u002F result = \"HELLO\"\n\u002F\u002F\u002F \u003C\u002Fcode>\n\u002F\u002F\u002F \u003C\u002Fexample>\n\u002F\u002F\u002F \u003Cremarks>Additional detail about behavior or performance.\u003C\u002Fremarks>\n\u002F\u002F\u002F \u003Cexception cref=\"T:System.ArgumentException\">When input is null.\u003C\u002Fexception>\n\u002F\u002F\u002F \u003Csee cref=\"T:MyLib.RelatedType\"\u002F>\n\u002F\u002F\u002F \u003Cseealso cref=\"M:MyLib.OtherModule.relatedFunction\"\u002F>\n```\n\n## F#-Specific Documentation Patterns\n\n### Discriminated Unions\n\nDocument each case separately — they appear as individual entries in API docs:\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>Represents a validation result.\u003C\u002Fsummary>\ntype ValidationResult =\n    \u002F\u002F\u002F \u003Csummary>Validation passed successfully.\u003C\u002Fsummary>\n    | Valid\n    \u002F\u002F\u002F \u003Csummary>Validation failed with error messages.\u003C\u002Fsummary>\n    \u002F\u002F\u002F \u003Cparam name=\"errors\">List of validation error messages.\u003C\u002Fparam>\n    | Invalid of errors: string list\n```\n\n### Computation Expression Builders\n\nDocument the builder type and its key methods. Focus on the user-facing CE syntax, not internal builder mechanics:\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Builder for the \u003Cc>result\u003C\u002Fc> computation expression.\n\u002F\u002F\u002F Enables railway-oriented programming with Result types.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n\u002F\u002F\u002F \u003Cexample>\n\u002F\u002F\u002F \u003Ccode>\n\u002F\u002F\u002F let validated = result {\n\u002F\u002F\u002F     let! name = validateName input\n\u002F\u002F\u002F     let! email = validateEmail input\n\u002F\u002F\u002F     return { Name = name; Email = email }\n\u002F\u002F\u002F }\n\u002F\u002F\u002F \u003C\u002Fcode>\n\u002F\u002F\u002F \u003C\u002Fexample>\ntype ResultBuilder() =\n    \u002F\u002F\u002F \u003Csummary>Wraps a value in \u003Cc>Ok\u003C\u002Fc>.\u003C\u002Fsummary>\n    member _.Return(x) = Ok x\n    \u002F\u002F\u002F \u003Csummary>Unwraps a \u003Cc>Result\u003C\u002Fc> and passes the \u003Cc>Ok\u003C\u002Fc> value to the continuation.\u003C\u002Fsummary>\n    member _.Bind(m, f) = Result.bind f m\n```\n\n### Active Patterns\n\nDocument the pattern and what it matches:\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Classifies an integer as even or odd.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n\u002F\u002F\u002F \u003Cparam name=\"n\">The integer to classify.\u003C\u002Fparam>\n\u002F\u002F\u002F \u003Creturns>\u003Cc>Even\u003C\u002Fc> when divisible by 2, \u003Cc>Odd\u003C\u002Fc> otherwise.\u003C\u002Freturns>\nlet (|Even|Odd|) n =\n    if n % 2 = 0 then Even else Odd\n```\n\n### Type Extensions\n\nDocument extension members the same as regular members — they appear alongside the extended type in API docs:\n\n```fsharp\ntype System.String with\n    \u002F\u002F\u002F \u003Csummary>\n    \u002F\u002F\u002F Returns \u003Cc>None\u003C\u002Fc> if the string is null or whitespace,\n    \u002F\u002F\u002F \u003Cc>Some value\u003C\u002Fc> otherwise.\n    \u002F\u002F\u002F \u003C\u002Fsummary>\n    member this.ToOption() =\n        if System.String.IsNullOrWhiteSpace(this) then None\n        else Some this\n```\n\n## Writing Good Summaries\n\nThe `\u003Csummary>` tag is the most visible part of API documentation. It appears in namespace listings, search results, and tooltips. Write summaries that help users decide whether this is what they need.\n\n**Focus on behavior and purpose:**\n```fsharp\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Retries a failing operation with exponential backoff,\n\u002F\u002F\u002F doubling the delay after each attempt.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n```\n\n**Avoid restating the signature:**\n```fsharp\n\u002F\u002F BAD: Tells the reader nothing they can't see from the type\n\u002F\u002F\u002F \u003Csummary>Takes a string and returns an int option.\u003C\u002Fsummary>\nlet tryParseInt (s: string) : int option = ...\n\n\u002F\u002F GOOD: Explains purpose and behavior\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Parses an integer from a string, returning None for invalid input.\n\u002F\u002F\u002F Handles leading\u002Ftrailing whitespace but not thousands separators.\n\u002F\u002F\u002F \u003C\u002Fsummary>\nlet tryParseInt (s: string) : int option = ...\n```\n\n**Include key constraints and edge cases in the summary when short enough:**\n```fsharp\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Returns the first N elements. If the collection has fewer than N elements,\n\u002F\u002F\u002F returns all elements without error.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n```\n\nFor longer discussion of edge cases, algorithms, or performance, use `\u003Cremarks>` to keep the summary concise.\n\n## Quality Checklist\n\nBefore considering API docs complete:\n- [ ] Every public module has a `\u003Csummary>`\n- [ ] Every public function has `\u003Csummary>` and `\u003Cparam>` tags\n- [ ] Every DU has case-level documentation\n- [ ] Every namespace has a `\u003Cnamespacedoc>` sentinel module\n- [ ] Cross-references use correct `cref` syntax\n- [ ] An `\u003Cexample>` exists for non-trivial functions\n- [ ] `dotnet fsdocs build` produces no doc-related warnings\n\n## Best Practices\n\n**DO:**\n- ✅ Write summaries that explain purpose and behavior, not implementation\n- ✅ Document each DU case individually — they are separate API entries\n- ✅ Use `\u003Cexample>` liberally — working examples are the most valuable doc\n- ✅ Cross-reference related types with `\u003Csee cref=\"...\"\u002F>`\n- ✅ Keep summaries concise — use `\u003Cremarks>` for extended discussion\n\n**DON'T:**\n- ❌ Restate the function signature in prose (\"Takes a string and returns an int\")\n- ❌ Leave DU cases undocumented — each case needs its own `\u002F\u002F\u002F`\n- ❌ Use `\u003Cc>` for multi-line code — use `\u003Ccode>` blocks instead\n- ❌ Skip the build verification — broken `cref` links are silent failures\n- ❌ Document private or internal members unless building with `--nonpublic`\n\n## Additional Resources\n\n### Reference Files\n- **`references\u002Fxml-doc-patterns.md`** — Comprehensive XML doc tag reference with F#-specific examples, cross-referencing patterns, markdown-in-comments mode, and common pitfalls\n\n## Implementation Workflow\n\n1. Build the project to verify it compiles (`dotnet build -c Release`)\n2. Identify all public API members that need documentation\n3. Audit existing doc comments for gaps and quality issues\n4. Add or improve `\u002F\u002F\u002F` XML doc comments in `.fs` source files\n5. Add `\u003Cnamespacedoc>` sentinel modules for each namespace\n6. Add `\u003Ccategory>` tags to organize large APIs\n7. Build docs (`dotnet fsdocs build --clean`) and verify rendered output\n\nFocus on writing doc comments that help library consumers understand purpose and usage, not implementation details.\n\n## Scope \u002F when to use\n\nUse this skill to **write or improve `\u002F\u002F\u002F` XML doc comments in `.fs` source files**\nso the generator produces high-quality API reference pages. It edits source, not\n`docs\u002F` content. For narrative tutorials use [[fsdocs-examples]]; for architecture\nand design prose use [[fsdocs-technical]]; to actually render and verify the pages\nuse [[fsdocs-build]]; and if the project is not yet wired for docs, run\n[[fsdocs-setup]] first.\n\n## Driven-library API\n\nThis skill drives the external **FSharp.Formatting** API-docs pipeline — there is\nno FS.Skia.UI backing `.fsi` surface. The driven contract is the F# XML\ndocumentation tag set consumed by the generator: `\u003Csummary>`, `\u003Cparam>`,\n`\u003Creturns>`, `\u003Cexample>`\u002F`\u003Ccode>`, `\u003Cremarks>`, `\u003Cexception>`, `\u003Csee>`\u002F`\u003Cseealso>`\nwith `cref:T:`\u002F`cref:M:`\u002F`cref:P:` targets, `\u003Ctypeparam>`, `\u003Ccategory>`, and the\n`\u003Cnamespacedoc>` sentinel-module convention. It requires\n`\u003CGenerateDocumentationFile>true\u003C\u002FGenerateDocumentationFile>` so the compiler emits\nthe XML the tool reads.\n\n## Persistent-problem mandate\n\n`cref` target syntax and supported XML-doc tags are version-sensitive and fail\nsilently (broken links, dropped sections) rather than erroring. Consult the\n**official online docs first** — both the FSharp.Formatting API-docs guide and the\nMicrosoft F# XML-documentation reference — before relying on a tag or `cref` form\ndocumented here, and verify rendered output rather than trusting the source builds.\n\n## Related\n\n- [[fsdocs-setup]] — enable `GenerateDocumentationFile` and scaffold the site\n- [[fsdocs-build]] — render and verify the API pages this skill feeds\n- [[fsdocs-examples]] — literate tutorials that complement API reference\n- [[fsdocs-technical]] — narrative docs that `cref`-link back to these API pages\n\n## Sources\n\n- FSharp.Formatting API-docs guide: https:\u002F\u002Ffsprojects.github.io\u002FFSharp.Formatting\u002Fapidocs.html\n- F# XML documentation reference (Microsoft Learn): https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Ffsharp\u002Flanguage-reference\u002Fxml-documentation\n- FSharp.Formatting repository: https:\u002F\u002Fgithub.com\u002Ffsprojects\u002FFSharp.Formatting\n","# Improve XML Doc Comments in F# Source Files\n\nAdd and improve `\u002F\u002F\u002F` XML documentation comments in F# source files so FSharp.Formatting generates high-quality API reference pages.\n\n**Key capabilities:**\n- Audit public API surface for missing or low-quality doc comments\n- Write idiomatic F# XML doc comments with proper tag usage\n- Document F#-specific constructs: discriminated unions, computation expressions, active patterns\n- Add namespace-level documentation via sentinel modules\n- Organize API docs with categories\n\n## Overview\n\nFSharp.Formatting generates API reference pages from compiled assemblies and their XML documentation files. The quality of these pages depends entirely on the `\u002F\u002F\u002F` comments in source code. This skill focuses on editing `.fs` source files to improve those comments — it does not create files in `docs\u002F`.\n\nEnsure `\u003CGenerateDocumentationFile>true\u003C\u002FGenerateDocumentationFile>` is set in project properties before starting. Without this, the compiler does not emit XML doc files.\n\n## Workflow\n\n### 1. Build to Verify Compilation\n\nBuild the project first to confirm it compiles cleanly:\n\n```\ndotnet build -c Release\n```\n\nFix any compilation errors before documenting. Documentation work requires a compilable codebase.\n\n### 2. Identify Public API Surface\n\nScan for all public declarations that will appear in generated API docs:\n- Modules and their public functions\u002Fvalues\n- Types (records, DUs, classes) and their members\n- Type extensions\n- Active patterns\n- Computation expression builders\n\nFocus on items visible to library consumers. Internal or private members do not appear in standard API docs.\n\nPrioritize by impact: types and functions that most users will encounter first deserve the best documentation. Start with the main entry points and work outward.\n\n### 3. Audit Existing Documentation\n\nFor each public API member, check:\n- Is there a `\u003Csummary>` at minimum?\n- Do functions with parameters have `\u003Cparam>` tags?\n- Do functions returning non-obvious types have `\u003Creturns>` tags?\n- Are there `\u003Cexample>` blocks for non-trivial usage?\n- Are discriminated union cases individually documented?\n\n### 4. Write XML Doc Comments\n\nApply `\u002F\u002F\u002F` comments to all public members. Follow the tag priority:\n\n**Essential (every public member):**\n- `\u003Csummary>` — one to three sentences describing purpose and behavior\n\n**Important (when applicable):**\n- `\u003Cparam name=\"x\">` — describe each parameter's purpose and constraints\n- `\u003Creturns>` — describe return value, especially for non-obvious types\n- `\u003Cexample>` — show typical usage with a code block\n- `\u003Cremarks>` — additional context, algorithms, performance notes\n\n**Supplemental:**\n- `\u003Cexception cref=\"T:System.ArgumentException\">` — document thrown exceptions\n- `\u003Csee cref=\"T:Namespace.Type\"\u002F>` — cross-reference related types\n- `\u003Cseealso cref=\"T:Namespace.Type\"\u002F>` — related reading\n- `\u003Ctypeparam name=\"'a\">` — describe generic type parameters\n\n### 5. Add Namespace Documentation\n\nCreate a sentinel module for each namespace to provide namespace-level docs:\n\n```fsharp\nnamespace MyLib.Core\n\n\u002F\u002F\u002F \u003Cnamespacedoc>\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Core types and functions for MyLib. Contains the primary domain\n\u002F\u002F\u002F model and essential operations.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n\u002F\u002F\u002F \u003C\u002Fnamespacedoc>\nmodule internal NamespaceDoc = ()\n```\n\nPlace this at the top of the first file in each namespace. The module must be `internal` — it exists only to carry the `\u003Cnamespacedoc>` tag.\n\n### 6. Organize with Categories\n\nGroup related members using `\u003Ccategory>` tags on types and modules:\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>String manipulation utilities.\u003C\u002Fsummary>\n\u002F\u002F\u002F \u003Ccategory>Text Processing\u003C\u002Fcategory>\nmodule StringOps =\n    \u002F\u002F ...\n```\n\nCategories create groupings on the namespace page, making large APIs navigable.\n\n### 7. Build and Verify\n\nBuild the documentation to verify comments render correctly:\n\n```\ndotnet fsdocs build --clean\n```\n\nCheck the generated API pages in `output\u002Freference\u002F` for formatting issues, broken cross-references, and missing content.\n\n## Quick Reference: Common Tags\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>Brief description of the member.\u003C\u002Fsummary>\n\u002F\u002F\u002F \u003Cparam name=\"input\">Description of the parameter.\u003C\u002Fparam>\n\u002F\u002F\u002F \u003Creturns>Description of the return value.\u003C\u002Freturns>\n\u002F\u002F\u002F \u003Cexample>\n\u002F\u002F\u002F \u003Ccode>\n\u002F\u002F\u002F let result = MyModule.transform \"hello\"\n\u002F\u002F\u002F \u002F\u002F result = \"HELLO\"\n\u002F\u002F\u002F \u003C\u002Fcode>\n\u002F\u002F\u002F \u003C\u002Fexample>\n\u002F\u002F\u002F \u003Cremarks>Additional detail about behavior or performance.\u003C\u002Fremarks>\n\u002F\u002F\u002F \u003Cexception cref=\"T:System.ArgumentException\">When input is null.\u003C\u002Fexception>\n\u002F\u002F\u002F \u003Csee cref=\"T:MyLib.RelatedType\"\u002F>\n\u002F\u002F\u002F \u003Cseealso cref=\"M:MyLib.OtherModule.relatedFunction\"\u002F>\n```\n\n## F#-Specific Documentation Patterns\n\n### Discriminated Unions\n\nDocument each case separately — they appear as individual entries in API docs:\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>Represents a validation result.\u003C\u002Fsummary>\ntype ValidationResult =\n    \u002F\u002F\u002F \u003Csummary>Validation passed successfully.\u003C\u002Fsummary>\n    | Valid\n    \u002F\u002F\u002F \u003Csummary>Validation failed with error messages.\u003C\u002Fsummary>\n    \u002F\u002F\u002F \u003Cparam name=\"errors\">List of validation error messages.\u003C\u002Fparam>\n    | Invalid of errors: string list\n```\n\n### Computation Expression Builders\n\nDocument the builder type and its key methods. Focus on the user-facing CE syntax, not internal builder mechanics:\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Builder for the \u003Cc>result\u003C\u002Fc> computation expression.\n\u002F\u002F\u002F Enables railway-oriented programming with Result types.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n\u002F\u002F\u002F \u003Cexample>\n\u002F\u002F\u002F \u003Ccode>\n\u002F\u002F\u002F let validated = result {\n\u002F\u002F\u002F     let! name = validateName input\n\u002F\u002F\u002F     let! email = validateEmail input\n\u002F\u002F\u002F     return { Name = name; Email = email }\n\u002F\u002F\u002F }\n\u002F\u002F\u002F \u003C\u002Fcode>\n\u002F\u002F\u002F \u003C\u002Fexample>\ntype ResultBuilder() =\n    \u002F\u002F\u002F \u003Csummary>Wraps a value in \u003Cc>Ok\u003C\u002Fc>.\u003C\u002Fsummary>\n    member _.Return(x) = Ok x\n    \u002F\u002F\u002F \u003Csummary>Unwraps a \u003Cc>Result\u003C\u002Fc> and passes the \u003Cc>Ok\u003C\u002Fc> value to the continuation.\u003C\u002Fsummary>\n    member _.Bind(m, f) = Result.bind f m\n```\n\n### Active Patterns\n\nDocument the pattern and what it matches:\n\n```fsharp\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Classifies an integer as even or odd.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n\u002F\u002F\u002F \u003Cparam name=\"n\">The integer to classify.\u003C\u002Fparam>\n\u002F\u002F\u002F \u003Creturns>\u003Cc>Even\u003C\u002Fc> when divisible by 2, \u003Cc>Odd\u003C\u002Fc> otherwise.\u003C\u002Freturns>\nlet (|Even|Odd|) n =\n    if n % 2 = 0 then Even else Odd\n```\n\n### Type Extensions\n\nDocument extension members the same as regular members — they appear alongside the extended type in API docs:\n\n```fsharp\ntype System.String with\n    \u002F\u002F\u002F \u003Csummary>\n    \u002F\u002F\u002F Returns \u003Cc>None\u003C\u002Fc> if the string is null or whitespace,\n    \u002F\u002F\u002F \u003Cc>Some value\u003C\u002Fc> otherwise.\n    \u002F\u002F\u002F \u003C\u002Fsummary>\n    member this.ToOption() =\n        if System.String.IsNullOrWhiteSpace(this) then None\n        else Some this\n```\n\n## Writing Good Summaries\n\nThe `\u003Csummary>` tag is the most visible part of API documentation. It appears in namespace listings, search results, and tooltips. Write summaries that help users decide whether this is what they need.\n\n**Focus on behavior and purpose:**\n```fsharp\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Retries a failing operation with exponential backoff,\n\u002F\u002F\u002F doubling the delay after each attempt.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n```\n\n**Avoid restating the signature:**\n```fsharp\n\u002F\u002F BAD: Tells the reader nothing they can't see from the type\n\u002F\u002F\u002F \u003Csummary>Takes a string and returns an int option.\u003C\u002Fsummary>\nlet tryParseInt (s: string) : int option = ...\n\n\u002F\u002F GOOD: Explains purpose and behavior\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Parses an integer from a string, returning None for invalid input.\n\u002F\u002F\u002F Handles leading\u002Ftrailing whitespace but not thousands separators.\n\u002F\u002F\u002F \u003C\u002Fsummary>\nlet tryParseInt (s: string) : int option = ...\n```\n\n**Include key constraints and edge cases in the summary when short enough:**\n```fsharp\n\u002F\u002F\u002F \u003Csummary>\n\u002F\u002F\u002F Returns the first N elements. If the collection has fewer than N elements,\n\u002F\u002F\u002F returns all elements without error.\n\u002F\u002F\u002F \u003C\u002Fsummary>\n```\n\nFor longer discussion of edge cases, algorithms, or performance, use `\u003Cremarks>` to keep the summary concise.\n\n## Quality Checklist\n\nBefore considering API docs complete:\n- [ ] Every public module has a `\u003Csummary>`\n- [ ] Every public function has `\u003Csummary>` and `\u003Cparam>` tags\n- [ ] Every DU has case-level documentation\n- [ ] Every namespace has a `\u003Cnamespacedoc>` sentinel module\n- [ ] Cross-references use correct `cref` syntax\n- [ ] An `\u003Cexample>` exists for non-trivial functions\n- [ ] `dotnet fsdocs build` produces no doc-related warnings\n\n## Best Practices\n\n**DO:**\n- ✅ Write summaries that explain purpose and behavior, not implementation\n- ✅ Document each DU case individually — they are separate API entries\n- ✅ Use `\u003Cexample>` liberally — working examples are the most valuable doc\n- ✅ Cross-reference related types with `\u003Csee cref=\"...\"\u002F>`\n- ✅ Keep summaries concise — use `\u003Cremarks>` for extended discussion\n\n**DON'T:**\n- ❌ Restate the function signature in prose (\"Takes a string and returns an int\")\n- ❌ Leave DU cases undocumented — each case needs its own `\u002F\u002F\u002F`\n- ❌ Use `\u003Cc>` for multi-line code — use `\u003Ccode>` blocks instead\n- ❌ Skip the build verification — broken `cref` links are silent failures\n- ❌ Document private or internal members unless building with `--nonpublic`\n\n## Additional Resources\n\n### Reference Files\n- **`references\u002Fxml-doc-patterns.md`** — Comprehensive XML doc tag reference with F#-specific examples, cross-referencing patterns, markdown-in-comments mode, and common pitfalls\n\n## Implementation Workflow\n\n1. Build the project to verify it compiles (`dotnet build -c Release`)\n2. Identify all public API members that need documentation\n3. Audit existing doc comments for gaps and quality issues\n4. Add or improve `\u002F\u002F\u002F` XML doc comments in `.fs` source files\n5. Add `\u003Cnamespacedoc>` sentinel modules for each namespace\n6. Add `\u003Ccategory>` tags to organize large APIs\n7. Build docs (`dotnet fsdocs build --clean`) and verify rendered output\n\nFocus on writing doc comments that help library consumers understand purpose and usage, not implementation details.\n\n## Scope \u002F when to use\n\nUse this skill to **write or improve `\u002F\u002F\u002F` XML doc comments in `.fs` source files**\nso the generator produces high-quality API reference pages. It edits source, not\n`docs\u002F` content. For narrative tutorials use [[fsdocs-examples]]; for architecture\nand design prose use [[fsdocs-technical]]; to actually render and verify the pages\nuse [[fsdocs-build]]; and if the project is not yet wired for docs, run\n[[fsdocs-setup]] first.\n\n## Driven-library API\n\nThis skill drives the external **FSharp.Formatting** API-docs pipeline — there is\nno FS.Skia.UI backing `.fsi` surface. The driven contract is the F# XML\ndocumentation tag set consumed by the generator: `\u003Csummary>`, `\u003Cparam>`,\n`\u003Creturns>`, `\u003Cexample>`\u002F`\u003Ccode>`, `\u003Cremarks>`, `\u003Cexception>`, `\u003Csee>`\u002F`\u003Cseealso>`\nwith `cref:T:`\u002F`cref:M:`\u002F`cref:P:` targets, `\u003Ctypeparam>`, `\u003Ccategory>`, and the\n`\u003Cnamespacedoc>` sentinel-module convention. It requires\n`\u003CGenerateDocumentationFile>true\u003C\u002FGenerateDocumentationFile>` so the compiler emits\nthe XML the tool reads.\n\n## Persistent-problem mandate\n\n`cref` target syntax and supported XML-doc tags are version-sensitive and fail\nsilently (broken links, dropped sections) rather than erroring. Consult the\n**official online docs first** — both the FSharp.Formatting API-docs guide and the\nMicrosoft F# XML-documentation reference — before relying on a tag or `cref` form\ndocumented here, and verify rendered output rather than trusting the source builds.\n\n## Related\n\n- [[fsdocs-setup]] — enable `GenerateDocumentationFile` and scaffold the site\n- [[fsdocs-build]] — render and verify the API pages this skill feeds\n- [[fsdocs-examples]] — literate tutorials that complement API reference\n- [[fsdocs-technical]] — narrative docs that `cref`-link back to these API pages\n\n## Sources\n\n- FSharp.Formatting API-docs guide: https:\u002F\u002Ffsprojects.github.io\u002FFSharp.Formatting\u002Fapidocs.html\n- F# XML documentation reference (Microsoft Learn): https:\u002F\u002Flearn.microsoft.com\u002Fdotnet\u002Ffsharp\u002Flanguage-reference\u002Fxml-documentation\n- FSharp.Formatting repository: https:\u002F\u002Fgithub.com\u002Ffsprojects\u002FFSharp.Formatting\n",{"name":5,"version":23,"description":7},"0.1.0","main","f943406829a9218b2882e09eb88d4ddb539c5e72",".agents\u002Fskills\u002Ffsdocs-api-doc",0,"https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI","https:\u002F\u002Fgithub.com\u002FEHotwagner","2026-06-16 16:16:52",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add EHotwagner\u002FFS-Skia-UI --skill fsdocs-api-doc",{"tool":37,"command":38},"bunx","bunx skills add EHotwagner\u002FFS-Skia-UI --skill fsdocs-api-doc",{"tool":40,"command":41},"pnpm","pnpm dlx skills add EHotwagner\u002FFS-Skia-UI --skill fsdocs-api-doc","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Ffsdocs-api-doc\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fxml-doc-patterns.md","REFERENCE","参考文档",15836,"https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Ffsdocs-api-doc\u002Freferences\u002Fxml-doc-patterns.md",[52,59,66,73,80,87],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":18},"01M72SGYR4T02T1HTS175E0V86","fs-skia-ui-widgets","Generated product guidance for Skia-rendered FS.Skia.UI Controls, rich text, chart controls, graph controls, DataGrid, and custom wrappers.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-ui-widgets\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M72SGVZJR1B117QK7TCC6E0J","fs-skia-testing","Assert generated-product expectations and evidence in a governed FS.Skia.UI product.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-testing\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M72SGTC5HZYEVVVZT4X51AZ3","fs-skia-skiaviewer","Wire a generated FS.Skia.UI product to the desktop viewer host.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-skiaviewer\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M72SGS47RPYPC9JTC39CC6EF","fs-skia-scene","Build pure scene descriptions in a generated FS.Skia.UI product.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-scene\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M72SGQF4G76C4NGSF69KZRRF","fs-skia-keyboard-input","Map keyboard input to product commands in a generated FS.Skia.UI product.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-keyboard-input\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":18},"01M72SGNJP3PMSS2VRP98G7Z42","fs-skia-elmish","Drive a generated FS.Skia.UI product through the pure Elmish adapter.","https:\u002F\u002Fgithub.com\u002FEHotwagner\u002FFS-Skia-UI\u002Fblob\u002Fmain\u002Ftemplate\u002Fproduct-skills\u002Ffs-skia-elmish\u002FSKILL.md",[],[]]