[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CCFSDT327SVXMYKSTYJDZ1":3,"skill-same:01M6CCFSDT327SVXMYKSTYJDZ1":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":28,"publishedAt":49,"linkOnly":50,"markdownContent":51,"markdownBody":52,"frontMatter":53,"refName":57,"commitSha":58,"skillDirectory":59,"forksCount":60,"repositoryHtmlUrl":61,"repositoryHomepageUrl":62,"ownerHtmlUrl":63,"ownerBlogUrl":62,"ownerDescription":64,"updatedAt":65,"install":66,"resources":79},"01M6CCFSDT327SVXMYKSTYJDZ1","docs-writing",null,"How Stigmer's documentation is written beyond the mechanics in docs\u002FSTYLE.md, covering the register per reader, the choice of a page's medium, alt text, tutorial sequences, the overview files that feed generated reference pages, and what to refuse. Use when writing or reviewing any page under docs or site content.","stigmer\u002Fstigmer","stigmer","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F255479904?v=4","01M6CCFBFXXRZC4ZVNS3JSDV4W","Stigmer","01M6CCFBKY7M8QGR4GH9TT35MY",9,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fstigmer\u002Fstigmer\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdocs-writing\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48],"writing","docs","docs writing","style","mechanics","pages","register","reference","reader","site","how","documentation","text","use","generated","files","overview","choice","page","tutorial","2026-11-10 10:12:30",false,"---\nname: docs-writing\ndescription:\n  How Stigmer's documentation is written beyond the mechanics in docs\u002FSTYLE.md,\n  covering the register per reader, the choice of a page's medium, alt text,\n  tutorial sequences, the overview files that feed generated reference pages,\n  and what to refuse. Use when writing or reviewing any page under docs or site\n  content.\npaths:\n  - docs\u002F**\n  - site\u002F**\n---\n\n# Writing Stigmer's documentation\n\n`docs\u002FSTYLE.md` holds the mechanics (headings, code blocks, MDX components, the\nclassification contract, the medium rule) and `docs\u002Fvocabulary.md` holds what\nStigmer is and who it is for, every term and the five writing contexts. Neither\nis restated here. This skill holds the doctrine those two apply: why the rules\nare what they are, and the judgement calls a page needs that no lint can make.\nThe package guide (`docs\u002FAGENTS.md`) carries the laws in one line each.\n\n## Match the register to the reader\n\nEvery page speaks to one reader: the developer adding agents to their product.\nAny sentence that says what Stigmer is uses the words in `docs\u002Fvocabulary.md`,\n\"What Stigmer is, and who it is for\", and its examples are jobs done inside a\ncustomer's product, never a chat and never code.\n\n`docs\u002Fvocabulary.md` defines five contexts (sales site, quickstart and\ntutorials, concepts and how-to, reference and SDK, README), each with its own\naudience and register. Identify the context before writing a sentence, then\ncalibrate.\n\n- When the context is unclear, write for the least technical reader in the\n  audience. Plain language is always safe; unnecessary jargon never is.\n- On the sales site and in introductory docs: replace jargon with plain words\n  (\"definition file\", not \"declarative manifest\"; \"keeps running even if\n  something crashes\", not \"durable execution with checkpoint recovery\"); when a\n  term such as API or YAML is unavoidable, explain it in the same sentence.\n  Analogies from the reader's own stack (their database, their sign-in provider,\n  their job queue) are welcome where they say where Stigmer sits; never an\n  analogy to a tool the reader may not run, such as Kubernetes or Temporal.\n- In reference and SDK docs: precise technical language, exact field names,\n  proto message types and CLI flags; do not re-explain what earlier pages\n  taught.\n- In architecture and contributor docs, references to Kubernetes, Docker and the\n  like are appropriate; the audience lives there.\n- Stigmer's own terms are proper nouns used consistently. Never a synonym.\n\n## Choose the medium with the rule, not by preference\n\nThe rule is in `docs\u002FSTYLE.md` (\"Classify every page\"), applied in order, first\nyes wins. Two doctrines sit behind it:\n\n- **Motion is for demonstration.** An animated tour is reserved for a flow whose\n  timing or cause-and-effect is the lesson. A reader working through a\n  quickstart wants to stop, compare their screen with ours and scroll back; an\n  animated tour makes all of that awkward. Getting-started journeys and console\n  procedures are screenshot journeys paced by the reader.\n- **The text fallback is a hard requirement.** The docs are read through three\n  channels: the rendered site, the markdown exports (`llms-full.txt` and the\n  per-page `.md` files) and the Copy-as-Markdown button. An embed is invisible\n  in the last two; it passes through as a dangling tag. Every visual therefore\n  contributes text to the exports (per-step prose, alt text, or the Mermaid\n  source itself), and the prose around an embed carries the information on its\n  own. A `Screen` contributes its alt text and a link to its picture: the export\n  turns the tag into a markdown image. A `Live` contributes its alt text, linked\n  to the demo. A `TerminalRecording` contributes its alt text and its last frame\n  as text. A `Diagram` contributes the text it stands for, kept beside its\n  drawing in `site\u002Fsrc\u002Fcomponents\u002Fvisuals\u002F`: the export turns the tag into that\n  text. A concept page's own system picture is a `Diagram`, drawn in the site's\n  language; every other diagram is Mermaid (`docs\u002FSTYLE.md`, \"Diagrams\").\n\n## Screens come from the visual suite\n\nA page shows a screen only as a picture stigmer's visual suite draws, so the\npicture fails a test the moment the product's look moves and is redrawn in the\nsame pull request. To show one:\n\n1. Put every value the page prints that the picture shows (a name, a message, a\n   host) in the page's example in `test\u002Fvisual\u002Fsrc\u002Fdocs-examples.ts`. The scene\n   draws from it, and the site's `docs-screens` test fails when the page and the\n   file disagree, so change both together.\n2. Add an entry to `test\u002Fvisual\u002Fsrc\u002Fshown.ts`: a gallery scene from\n   `test\u002Fvisual\u002Fsrc\u002Fcatalog.ts`, the size it is drawn at, and a `clip` around\n   the part of the screen the step acts on. A screen the gallery does not draw\n   yet needs its scene first (`test\u002Fvisual\u002FREADME.md`, \"Add a scene\"); a form\n   the step fills, or a tab or menu it opens, is reached by the scene's acts.\n3. `make test-visual UPDATE=1` mints the picture; review it like any screenshot.\n4. Embed it with `\u003CScreen name=\"…\" alt=\"…\" \u002F>` right after the step it shows.\n\nPicture the steps a reader acts on or must recognise, cropped to that part of\nthe screen; navigation and other sites' screens (Slack's, Meta's, an OAuth\nprovider's) stay prose. A hand-captured screenshot rots with no signal, so it is\nnever added, not even as a placeholder. `make check-docs-inventory` holds every\n`still` and `screenshot-journey` page to at least one `\u003CScreen>` and every other\npage to none; a page still waiting for its pictures is listed, with its reason,\nin `OWED_PICTURES` (`site\u002Fsrc\u002Flib\u002Fdocs-inventory.ts`).\n\n## Live demos come from the visual suite too\n\nAn `interactive` page embeds the kit itself, live: `\u003CLive name=\"…\" alt=\"…\" \u002F>`\nframes a gallery scene in the gallery's docs mode, where a scripted server\nanswers a reader's send, approval and Stop with one scripted turn (the kit's\nscenario catalogue holds it). The demos are listed in `test\u002Fvisual\u002Fsrc\u002Flive.ts`;\na scene the list lacks gets its entry there (`test\u002Fvisual\u002FREADME.md`, \"Live\ndemos\"), and the visual suite's live spec drives it. The theming page's\n`\u003CThemePlayground \u002F>` is one of them, with the code to copy. Never build a demo\nfor a page: the docs had one until it went stale with every refactor, and the\ngallery is drawn by the code the screenshot check already holds.\n\n## Terminal recordings come from the terminal kit\n\nAn `animated-tour` page about the terminal plays a recording:\n`\u003CTerminalRecording name=\"…\" alt=\"…\" \u002F>`. A recording is the terminal kit's\n`SessionView` drawn over a story of the scenario catalogue one event at a time,\nlisted in `sdk\u002Fink\u002Fsrc\u002Frecordings.ts` and held, frame by frame, by the kit's\ntest (`sdk\u002Fink\u002Fsrc\u002F__tests__\u002Frecordings.test.tsx`), so a change to the\nterminal's look fails there and redraws the docs in the same pull request. A new\nrecording gets its entry there and is minted with `npx vitest run -u` in\n`sdk\u002Fink`. Never record a real terminal for a page: its timing varies and it\ndrifts with no test noticing. An `animated-tour` page with nothing to play stays\nprose, code and diagrams until it has a recording.\n\n## Alt text describes the screen\n\nAlt text is written for a reader who cannot see the image: it describes what the\nimage shows, not what the reader should feel about it, and it is authored in the\nMDX beside the image. It is also what the markdown exports carry in the image's\nplace.\n\n## Tutorials and learning paths\n\nFor any content where pages form a sequence:\n\n- **Narrative continuity.** Each page opens on what the reader accomplished on\n  the previous page and closes by motivating the next with a concrete,\n  functional reason. Test: read only the first and last paragraph of each page;\n  can you reconstruct the order without the sidebar?\n- **Aha-moment design.** Each tutorial names one moment where the reader sees\n  something work. State it in \"What you'll build\", deliver it when the reader\n  runs the command, reinforce it in \"What just happened\". Test: point to the\n  exact step where the reader's screen changes in a way that proves the concept.\n  If the payoff is only intellectual, the tutorial is an explanation in\n  disguise.\n- **One new concept per page.** Defer what the reader does not need yet.\n- **Implicit defaults.** Use the platform's sensible default without asking the\n  reader to configure anything; introduce configuration when there is a reason\n  to customise.\n- **The bridge.** Every page in a sequence ends with a \"Next step\" that answers\n  two questions: what can the reader not do yet, and what will the next page\n  teach? The motivation is a gap the reader can feel, never navigational. Good:\n  \"Your agent made the variance report, but it can't reach your customers'\n  ledgers yet. Let's connect it.\" Bad: \"Continue to the next tutorial.\"\n- Entry-point ordering, path convergence and prerequisite chains belong to the\n  information architecture; a page author does not decide path structure.\n\n## Code examples compile, or say why they cannot\n\nEvery TypeScript, Go, Python and Java block is compiled against the SDK it shows\n(`docs\u002FSTYLE.md`, \"Code examples compile\", has the mechanics). Write each one as\na reader will paste it:\n\n- Show the imports. A page whose examples share them shows them once in a\n  visible `prelude` block per language; a single example imports in place.\n- Take as given only the client: `stigmer` or `client` in TypeScript, `client`\n  and `ctx` in Go, `client` in Python and Java. A name the page's prose\n  introduces (a `user` the previous step signed in, an `accountId` the last call\n  returned) is declared in the block's hidden setup, above `\u002F\u002F ---cut---`\n  (`# ---cut---` in Python). The setup holds declarations and the imports they\n  alone need, never an import the visible code uses and never logic the reader\n  needs; if it carries meaning, it moves into the body. The prose still names\n  the given, as it always has.\n- Use the SDK's real names and types: the proto message a method takes, an enum\n  value rather than its string, the field a client exposes. The resource\n  reference pages show each language's form.\n- An example that returns a value is the function it belongs to.\n- Mark a block `no-compile=\"reason\"` only when it cannot compile and should not:\n  pseudo-code, a sketch with arguments elided, a wrong value shown beside a\n  right one. The reason says which.\n\nThe gate's list of blocks allowed to fail today may only shrink; never add to\nit.\n\n## Reference pages generated from protos\n\nSDK reference pages are generated from the proto schemas; the generator lives\nunder `tools\u002Fcodegen\u002F` and the comment convention it reads is owned by\n`tools\u002Fcodegen\u002Fsrc\u002Finternalcomment\u002Finternalcomment.ts` (the `apis\u002FAGENTS.md`\nlaws state it). Proto comments serve proto readers; the hand-written overview\nfile in the `docs` folder beside a resource's protos (for example\n`apis\u002Fai\u002Fstigmer\u002Fagentic\u002Fagent\u002Fdocs\u002Foverview.md`) serves SDK users and becomes\nthe reference page's first section verbatim. Do not make one text serve both\naudiences with markers or keywords.\n\nAn overview file is written in the reference register and the Diátaxis reference\ntype: two or three sentences on what the resource is and configures, then one\nminimal, representative YAML example in a standard fenced block (every YAML\nblock under `docs\u002F` is contract-validated, so it must apply as written). No\nfrontmatter, no metadata, no duplication of what the generated Methods and Types\nsections already say.\n\n## What to refuse\n\n- Documentation that requires the reader to already understand the thing being\n  documented.\n- A page added, moved or deleted without its classification entry changing in\n  the same commit.\n- A hand-captured screenshot, even as a placeholder.\n- An animated tour for content the reader works through at their own pace.\n- A visual that leaves the markdown exports with nothing.\n- On the sales site or in introductory docs, an analogy to a tool the reader may\n  not run.\n- An example from coding work (pull-request review, code generation).\n- Filler (\"it should be noted that\", \"it is important to understand\").\n- Two Diátaxis types on one page.\n- A measured Stigmer-versus-Claude comparison, in a table, in prose or through a\n  fixture. The harness benchmark (`make benchmark-harnesses`,\n  `test\u002Fconformance`) is an internal instrument and this refusal is its rule's\n  home: an Agent performs best in the harness and models built for it, so a\n  generic comparison on a handful of prompts tells a reader nothing about their\n  Agent, and the platform's own evaluation tooling is where they measure it. A\n  page explains how the harnesses differ and never quotes a measurement between\n  them.\n","# Writing Stigmer's documentation\n\n`docs\u002FSTYLE.md` holds the mechanics (headings, code blocks, MDX components, the\nclassification contract, the medium rule) and `docs\u002Fvocabulary.md` holds what\nStigmer is and who it is for, every term and the five writing contexts. Neither\nis restated here. This skill holds the doctrine those two apply: why the rules\nare what they are, and the judgement calls a page needs that no lint can make.\nThe package guide (`docs\u002FAGENTS.md`) carries the laws in one line each.\n\n## Match the register to the reader\n\nEvery page speaks to one reader: the developer adding agents to their product.\nAny sentence that says what Stigmer is uses the words in `docs\u002Fvocabulary.md`,\n\"What Stigmer is, and who it is for\", and its examples are jobs done inside a\ncustomer's product, never a chat and never code.\n\n`docs\u002Fvocabulary.md` defines five contexts (sales site, quickstart and\ntutorials, concepts and how-to, reference and SDK, README), each with its own\naudience and register. Identify the context before writing a sentence, then\ncalibrate.\n\n- When the context is unclear, write for the least technical reader in the\n  audience. Plain language is always safe; unnecessary jargon never is.\n- On the sales site and in introductory docs: replace jargon with plain words\n  (\"definition file\", not \"declarative manifest\"; \"keeps running even if\n  something crashes\", not \"durable execution with checkpoint recovery\"); when a\n  term such as API or YAML is unavoidable, explain it in the same sentence.\n  Analogies from the reader's own stack (their database, their sign-in provider,\n  their job queue) are welcome where they say where Stigmer sits; never an\n  analogy to a tool the reader may not run, such as Kubernetes or Temporal.\n- In reference and SDK docs: precise technical language, exact field names,\n  proto message types and CLI flags; do not re-explain what earlier pages\n  taught.\n- In architecture and contributor docs, references to Kubernetes, Docker and the\n  like are appropriate; the audience lives there.\n- Stigmer's own terms are proper nouns used consistently. Never a synonym.\n\n## Choose the medium with the rule, not by preference\n\nThe rule is in `docs\u002FSTYLE.md` (\"Classify every page\"), applied in order, first\nyes wins. Two doctrines sit behind it:\n\n- **Motion is for demonstration.** An animated tour is reserved for a flow whose\n  timing or cause-and-effect is the lesson. A reader working through a\n  quickstart wants to stop, compare their screen with ours and scroll back; an\n  animated tour makes all of that awkward. Getting-started journeys and console\n  procedures are screenshot journeys paced by the reader.\n- **The text fallback is a hard requirement.** The docs are read through three\n  channels: the rendered site, the markdown exports (`llms-full.txt` and the\n  per-page `.md` files) and the Copy-as-Markdown button. An embed is invisible\n  in the last two; it passes through as a dangling tag. Every visual therefore\n  contributes text to the exports (per-step prose, alt text, or the Mermaid\n  source itself), and the prose around an embed carries the information on its\n  own. A `Screen` contributes its alt text and a link to its picture: the export\n  turns the tag into a markdown image. A `Live` contributes its alt text, linked\n  to the demo. A `TerminalRecording` contributes its alt text and its last frame\n  as text. A `Diagram` contributes the text it stands for, kept beside its\n  drawing in `site\u002Fsrc\u002Fcomponents\u002Fvisuals\u002F`: the export turns the tag into that\n  text. A concept page's own system picture is a `Diagram`, drawn in the site's\n  language; every other diagram is Mermaid (`docs\u002FSTYLE.md`, \"Diagrams\").\n\n## Screens come from the visual suite\n\nA page shows a screen only as a picture stigmer's visual suite draws, so the\npicture fails a test the moment the product's look moves and is redrawn in the\nsame pull request. To show one:\n\n1. Put every value the page prints that the picture shows (a name, a message, a\n   host) in the page's example in `test\u002Fvisual\u002Fsrc\u002Fdocs-examples.ts`. The scene\n   draws from it, and the site's `docs-screens` test fails when the page and the\n   file disagree, so change both together.\n2. Add an entry to `test\u002Fvisual\u002Fsrc\u002Fshown.ts`: a gallery scene from\n   `test\u002Fvisual\u002Fsrc\u002Fcatalog.ts`, the size it is drawn at, and a `clip` around\n   the part of the screen the step acts on. A screen the gallery does not draw\n   yet needs its scene first (`test\u002Fvisual\u002FREADME.md`, \"Add a scene\"); a form\n   the step fills, or a tab or menu it opens, is reached by the scene's acts.\n3. `make test-visual UPDATE=1` mints the picture; review it like any screenshot.\n4. Embed it with `\u003CScreen name=\"…\" alt=\"…\" \u002F>` right after the step it shows.\n\nPicture the steps a reader acts on or must recognise, cropped to that part of\nthe screen; navigation and other sites' screens (Slack's, Meta's, an OAuth\nprovider's) stay prose. A hand-captured screenshot rots with no signal, so it is\nnever added, not even as a placeholder. `make check-docs-inventory` holds every\n`still` and `screenshot-journey` page to at least one `\u003CScreen>` and every other\npage to none; a page still waiting for its pictures is listed, with its reason,\nin `OWED_PICTURES` (`site\u002Fsrc\u002Flib\u002Fdocs-inventory.ts`).\n\n## Live demos come from the visual suite too\n\nAn `interactive` page embeds the kit itself, live: `\u003CLive name=\"…\" alt=\"…\" \u002F>`\nframes a gallery scene in the gallery's docs mode, where a scripted server\nanswers a reader's send, approval and Stop with one scripted turn (the kit's\nscenario catalogue holds it). The demos are listed in `test\u002Fvisual\u002Fsrc\u002Flive.ts`;\na scene the list lacks gets its entry there (`test\u002Fvisual\u002FREADME.md`, \"Live\ndemos\"), and the visual suite's live spec drives it. The theming page's\n`\u003CThemePlayground \u002F>` is one of them, with the code to copy. Never build a demo\nfor a page: the docs had one until it went stale with every refactor, and the\ngallery is drawn by the code the screenshot check already holds.\n\n## Terminal recordings come from the terminal kit\n\nAn `animated-tour` page about the terminal plays a recording:\n`\u003CTerminalRecording name=\"…\" alt=\"…\" \u002F>`. A recording is the terminal kit's\n`SessionView` drawn over a story of the scenario catalogue one event at a time,\nlisted in `sdk\u002Fink\u002Fsrc\u002Frecordings.ts` and held, frame by frame, by the kit's\ntest (`sdk\u002Fink\u002Fsrc\u002F__tests__\u002Frecordings.test.tsx`), so a change to the\nterminal's look fails there and redraws the docs in the same pull request. A new\nrecording gets its entry there and is minted with `npx vitest run -u` in\n`sdk\u002Fink`. Never record a real terminal for a page: its timing varies and it\ndrifts with no test noticing. An `animated-tour` page with nothing to play stays\nprose, code and diagrams until it has a recording.\n\n## Alt text describes the screen\n\nAlt text is written for a reader who cannot see the image: it describes what the\nimage shows, not what the reader should feel about it, and it is authored in the\nMDX beside the image. It is also what the markdown exports carry in the image's\nplace.\n\n## Tutorials and learning paths\n\nFor any content where pages form a sequence:\n\n- **Narrative continuity.** Each page opens on what the reader accomplished on\n  the previous page and closes by motivating the next with a concrete,\n  functional reason. Test: read only the first and last paragraph of each page;\n  can you reconstruct the order without the sidebar?\n- **Aha-moment design.** Each tutorial names one moment where the reader sees\n  something work. State it in \"What you'll build\", deliver it when the reader\n  runs the command, reinforce it in \"What just happened\". Test: point to the\n  exact step where the reader's screen changes in a way that proves the concept.\n  If the payoff is only intellectual, the tutorial is an explanation in\n  disguise.\n- **One new concept per page.** Defer what the reader does not need yet.\n- **Implicit defaults.** Use the platform's sensible default without asking the\n  reader to configure anything; introduce configuration when there is a reason\n  to customise.\n- **The bridge.** Every page in a sequence ends with a \"Next step\" that answers\n  two questions: what can the reader not do yet, and what will the next page\n  teach? The motivation is a gap the reader can feel, never navigational. Good:\n  \"Your agent made the variance report, but it can't reach your customers'\n  ledgers yet. Let's connect it.\" Bad: \"Continue to the next tutorial.\"\n- Entry-point ordering, path convergence and prerequisite chains belong to the\n  information architecture; a page author does not decide path structure.\n\n## Code examples compile, or say why they cannot\n\nEvery TypeScript, Go, Python and Java block is compiled against the SDK it shows\n(`docs\u002FSTYLE.md`, \"Code examples compile\", has the mechanics). Write each one as\na reader will paste it:\n\n- Show the imports. A page whose examples share them shows them once in a\n  visible `prelude` block per language; a single example imports in place.\n- Take as given only the client: `stigmer` or `client` in TypeScript, `client`\n  and `ctx` in Go, `client` in Python and Java. A name the page's prose\n  introduces (a `user` the previous step signed in, an `accountId` the last call\n  returned) is declared in the block's hidden setup, above `\u002F\u002F ---cut---`\n  (`# ---cut---` in Python). The setup holds declarations and the imports they\n  alone need, never an import the visible code uses and never logic the reader\n  needs; if it carries meaning, it moves into the body. The prose still names\n  the given, as it always has.\n- Use the SDK's real names and types: the proto message a method takes, an enum\n  value rather than its string, the field a client exposes. The resource\n  reference pages show each language's form.\n- An example that returns a value is the function it belongs to.\n- Mark a block `no-compile=\"reason\"` only when it cannot compile and should not:\n  pseudo-code, a sketch with arguments elided, a wrong value shown beside a\n  right one. The reason says which.\n\nThe gate's list of blocks allowed to fail today may only shrink; never add to\nit.\n\n## Reference pages generated from protos\n\nSDK reference pages are generated from the proto schemas; the generator lives\nunder `tools\u002Fcodegen\u002F` and the comment convention it reads is owned by\n`tools\u002Fcodegen\u002Fsrc\u002Finternalcomment\u002Finternalcomment.ts` (the `apis\u002FAGENTS.md`\nlaws state it). Proto comments serve proto readers; the hand-written overview\nfile in the `docs` folder beside a resource's protos (for example\n`apis\u002Fai\u002Fstigmer\u002Fagentic\u002Fagent\u002Fdocs\u002Foverview.md`) serves SDK users and becomes\nthe reference page's first section verbatim. Do not make one text serve both\naudiences with markers or keywords.\n\nAn overview file is written in the reference register and the Diátaxis reference\ntype: two or three sentences on what the resource is and configures, then one\nminimal, representative YAML example in a standard fenced block (every YAML\nblock under `docs\u002F` is contract-validated, so it must apply as written). No\nfrontmatter, no metadata, no duplication of what the generated Methods and Types\nsections already say.\n\n## What to refuse\n\n- Documentation that requires the reader to already understand the thing being\n  documented.\n- A page added, moved or deleted without its classification entry changing in\n  the same commit.\n- A hand-captured screenshot, even as a placeholder.\n- An animated tour for content the reader works through at their own pace.\n- A visual that leaves the markdown exports with nothing.\n- On the sales site or in introductory docs, an analogy to a tool the reader may\n  not run.\n- An example from coding work (pull-request review, code generation).\n- Filler (\"it should be noted that\", \"it is important to understand\").\n- Two Diátaxis types on one page.\n- A measured Stigmer-versus-Claude comparison, in a table, in prose or through a\n  fixture. The harness benchmark (`make benchmark-harnesses`,\n  `test\u002Fconformance`) is an internal instrument and this refusal is its rule's\n  home: an Agent performs best in the harness and models built for it, so a\n  generic comparison on a handful of prompts tells a reader nothing about their\n  Agent, and the platform's own evaluation tooling is where they measure it. A\n  page explains how the harnesses differ and never quotes a measurement between\n  them.\n",{"name":5,"paths":54,"description":7},[55,56],"docs\u002F**","site\u002F**","main","7b43d462fc7be62a629567ceaecfed197c8a1c1b",".agents\u002Fskills\u002Fdocs-writing",6,"https:\u002F\u002Fgithub.com\u002Fstigmer\u002Fstigmer","https:\u002F\u002Fstigmer.ai","https:\u002F\u002Fgithub.com\u002Fstigmer","The open-source backend for the agents in your product.","2026-11-13 03:32:31",{"source":8,"skillName":5,"commands":67,"prompt":77,"zipAvailable":78},[68,71,74],{"tool":69,"command":70},"npx","npx skills add stigmer\u002Fstigmer --skill docs-writing",{"tool":72,"command":73},"bunx","bunx skills add stigmer\u002Fstigmer --skill docs-writing",{"tool":75,"command":76},"pnpm","pnpm dlx skills add stigmer\u002Fstigmer --skill docs-writing","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fstigmer\u002Fstigmer\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdocs-writing\u002FSKILL.md",true,[],[81,102,122,139,153,169],{"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":92,"publishedAt":49},"01M6CCSERKR4YRSZJ2TB6B0X60","writing-hookify-rules","This skill should be used when the user asks to \"create a hookify rule\", \"write a hook rule\", \"configure hookify\", \"add a hookify rule\", or needs guidance on hookify rule syntax and patterns.","https:\u002F\u002Fgithub.com\u002Fstigmer\u002Fstigmer\u002Fblob\u002Fmain\u002Ftest\u002Fsupport\u002Ffixtures\u002Fclaude-plugins\u002Fhookify\u002Fskills\u002Fwriting-rules\u002FSKILL.md",[87,88,91],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":89,"categoryName":90,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},[29,93,94,95,96,97,98,99,100,101],"Writing Hookify Rules","Rules","hookify rules","create","guidance","user","write","configure","syntax",{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":114,"publishedAt":49},"01M6CCSC63RKCGC2S1EZDEMXZE","sql-migrations","Write safe database schema migrations - reversible steps, online index builds, and backfills in batches.","https:\u002F\u002Fgithub.com\u002Fstigmer\u002Fstigmer\u002Fblob\u002Fmain\u002Ftest\u002Fconformance\u002Ffixtures\u002Fworking-agent\u002Fskills\u002Fsql-migrations\u002FSKILL.md",[108,111],{"categoryNo":109,"categoryName":110,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":112,"categoryName":113,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000033","数据分析师",[115,116,117,118,99,119,120,121],"sql","sql migrations","migrations","schema","index","database","safe",{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":128,"publishedAt":49},"01M6CCS9Q8E0R3TYHPZHCPN0JZ","repo-conventions","How to change Go code in this repository - error wrapping, table-driven tests, doc comments, no new dependencies, and running go test before finishing.","https:\u002F\u002Fgithub.com\u002Fstigmer\u002Fstigmer\u002Fblob\u002Fmain\u002Ftest\u002Fconformance\u002Ffixtures\u002Fworking-agent\u002Fskills\u002Frepo-conventions\u002FSKILL.md",[],[129,130,131,132,133,134,135,136,137,138,39],"repo","repo conventions","table","go","test","change","doc comments","code","repository","doc",{"skillNo":140,"name":141,"nameZh":6,"description":142,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":143,"categories":144,"keywords":145,"publishedAt":49},"01M6CCS7F2D1YZ9H3N63XTEV09","incident-postmortem","Write a blameless incident postmortem - timeline, impact, root cause, contributing factors and follow-up actions with owners.","https:\u002F\u002Fgithub.com\u002Fstigmer\u002Fstigmer\u002Fblob\u002Fmain\u002Ftest\u002Fconformance\u002Ffixtures\u002Fworking-agent\u002Fskills\u002Fincident-postmortem\u002FSKILL.md",[],[146,147,99,148,149,150,151,152],"incident postmortem","postmortem","contributing","actions","timeline","owners","up",{"skillNo":154,"name":155,"nameZh":6,"description":156,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":157,"categories":158,"keywords":163,"publishedAt":49},"01M6CCS4W1D2K257KHC40HS8JG","data-analysis","Summarise a data export or table - lead with the key finding and give every number its baseline or comparison.","https:\u002F\u002Fgithub.com\u002Fstigmer\u002Fstigmer\u002Fblob\u002Fmain\u002Ftest\u002Fconformance\u002Ffixtures\u002Fworking-agent\u002Fskills\u002Fdata-analysis\u002FSKILL.md",[159,162],{"categoryNo":160,"categoryName":161,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000013","分析与可视化",{"categoryNo":112,"categoryName":113,"taxonomyType":26,"taxonomyTypeDesc":27},[164,165,166,167,131,168],"analysis","data analysis","data","baseline","export",{"skillNo":170,"name":171,"nameZh":6,"description":172,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":173,"categories":174,"keywords":175,"publishedAt":49},"01M6CCS2MNQYK9S24AYHJAVPWF","customer-support","Answer customer questions about orders, returns and refunds from the written policies and the order system, ending with a clear next step.","https:\u002F\u002Fgithub.com\u002Fstigmer\u002Fstigmer\u002Fblob\u002Fmain\u002Ftest\u002Fconformance\u002Ffixtures\u002Fworking-agent\u002Fskills\u002Fcustomer-support\u002FSKILL.md",[],[176,177,178,179,180,181],"support","customer","customer support","system","refunds","returns"]