[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71FCW1WDGC4XKYHWW6A3MB7":3,"skill-same:01M71FCW1WDGC4XKYHWW6A3MB7":82},{"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":54,"commitSha":55,"skillDirectory":56,"forksCount":14,"repositoryHtmlUrl":57,"repositoryHomepageUrl":6,"ownerHtmlUrl":58,"ownerBlogUrl":59,"ownerDescription":60,"updatedAt":61,"install":62,"resources":75},"01M71FCW1WDGC4XKYHWW6A3MB7","diataxis-explanation",null,"Write, expand, or audit explanation — understanding-oriented documentation in the Diátaxis sense: discursive discussion that deepens the reader's grasp of a topic, read away from the work itself. Use whenever the user wants an architecture overview, design-rationale or \"why did we build it this way\" doc, concept guide, background or theory piece, ADR-style context, a \"philosophy of X\" or \"about X\" article, or asks to capture the reasoning behind a decision — even if they never say \"explanation\". Also loaded by the `diataxis` router when the compass points to cognition + acquisition: the reader wants to *understand*, as *study*. If the content is facts to consult mid-work, that's `diataxis-reference`; if it directs a task, that's `diataxis-how-to`. When the type is in doubt or mixed, consult the `diataxis` skill first.","esond\u002Fskills","esond","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F4650644?v=4","01M71FCJGKDH30JSHK6XJZXN8Y","Eric Sondergard","01M71FCJHP4WCJVP4HVMEW1KB2",0,"MIT","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs\u002Fskills\u002Fdiataxis-explanation\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],"explanation","diataxis explanation","diataxis","read","why","audit","how","article","work","philosophy","acquisition","documentation","router","consult","architecture","when","design","decision","expand","never","2026-11-10 10:12:30",false,"---\nname: diataxis-explanation\ndescription: >-\n  Write, expand, or audit explanation — understanding-oriented documentation\n  in the Diátaxis sense: discursive discussion that deepens the reader's grasp\n  of a topic, read away from the work itself. Use whenever the user wants an\n  architecture overview, design-rationale or \"why did we build it this way\"\n  doc, concept guide, background or theory piece, ADR-style context, a\n  \"philosophy of X\" or \"about X\" article, or asks to capture the reasoning\n  behind a decision — even if they never say \"explanation\". Also loaded by\n  the `diataxis` router when the compass points to cognition + acquisition:\n  the reader wants to *understand*, as *study*. If the content is facts to\n  consult mid-work, that's `diataxis-reference`; if it directs a task, that's\n  `diataxis-how-to`. When the type is in doubt or mixed, consult the\n  `diataxis` skill first.\n---\n\n# diataxis-explanation\n\nExplanation is **discussion that permits reflection** — the documentation a practitioner reads away from the keyboard, the way a cook reads *On Food and Cooking*: not to follow a recipe, but to understand the craft in a way that changes their practice. It answers the question \"can you tell me about…?\" Diátaxis places explanation at *cognition* + *acquisition*: propositional knowledge, in service of study.\n\nIts characteristic problem isn't being written badly — it's not being written at all. The *why* of a system ends up scattered through commit messages, review threads, and hallway conversations, because explanation has no obvious owner. Writing it down as a first-class document is most of the battle.\n\n## Check you're writing the right thing\n\n- The content is **facts consulted while working** — options, parameters, structures → `diataxis-reference`. The boundary test: reference serves the reader mid-work; explanation serves the reader who has stepped back. Lists and tables usually mean reference; \"tell me more about…\" means explanation.\n- The content **directs a task** → `diataxis-how-to`.\n- The content **teaches a beginner by doing** → `diataxis-tutorial`.\n- Mixed or unclear → step back to the `diataxis` router and run the compass.\n\n## Step 1 — Frame the \"about\"\n\nAn explanation's title carries an implicit *about*: \"About user authentication,\" \"On caching strategy,\" \"Why the scheduler is cooperative.\" Fix the topic and its altitude first:\n\n1. **Name the subject** as a topic, not a task.\n2. **Choose the bounds.** Explanation may range — history, alternatives, tradeoffs — but around a bounded subject. If the scope is \"everything,\" it's several articles.\n3. **Know the reader's question.** What understanding are they missing that this article supplies? Design decisions, constraints, and history the code can't show are the highest-value material.\n\n## Step 2 — Gather the why\n\nExplanation is the one type whose raw material is mostly *not* in the artifact. Mine where the reasoning actually lives: design docs, ADRs, commit messages, PR discussions, issue threads, the user's own memory. Interview the user for what nothing else records — \"why not the obvious alternative?\" is usually the most productive question. Then verify any claims about the current system against the current system.\n\n## Step 3 — Write it\n\nExplanation has permissions the other three types deny — use them:\n\n- **Make connections.** Link the subject to related topics, to the rest of the system, to things outside it entirely. Weaving fragments into a coherent web is the job.\n- **Provide context.** Design decisions, historical reasons, technical constraints, with concrete examples: \"The reason for x is because historically, y…\"\n- **Approach from multiple directions.** Explanation may circle its subject; analogy is a legitimate tool: \"An x in system y is analogous to a w in system z. However…\"\n- **Have opinions.** All human knowledge is invested with opinion, and explanation is where it's admitted: \"W is better than z, because…\" Weigh alternatives honestly: \"Some users prefer w (because z). This can be a good approach, but…\"\n- **Stay off the tools.** The reader is reflecting, not executing. The moment the prose says \"now run…\", it has drifted.\n\n## Step 4 — The drift checklist\n\nUse this on your own draft, and as the audit lens when the `diataxis` router sends an existing explanation here. An audit invocation runs only this step — skip Steps 1–3 and report findings without editing; edits wait for explicit confirmation — the router's gate, or the user's when invoked directly. The repair move is usually **relocation — or consolidation**.\n\n- Instruction or procedure creeping in → relocate to a how-to guide or tutorial; link.\n- Dry enumerations of options, parameters, structures → relocate to reference; link.\n- The inverse problem — explanatory fragments scattered across tutorials, how-tos, and reference entries elsewhere in the doc set → gather them *into* this article and leave links behind. Consolidation is explanation's distinctive audit move.\n- Opinion presented as neutral fact without the reasoning → either supply the why or mark the perspective.\n- Unbounded scope, three subjects in one article → split along topic lines.\n- Claims about the system that no longer match the system → verify and update; rationale docs go stale silently.\n\n## Things not to do\n\n- **Don't** instruct. No steps, no commands to run.\n- **Don't** turn into a catalog. Exhaustive facts belong in reference.\n- **Don't** feign neutrality. Reference must be neutral; explanation earns trust by showing its reasoning, alternatives and all.\n- **Don't** leave the why unwritten because it feels \"obvious to the team.\" That's exactly the knowledge that leaves when people do.\n","# diataxis-explanation\n\nExplanation is **discussion that permits reflection** — the documentation a practitioner reads away from the keyboard, the way a cook reads *On Food and Cooking*: not to follow a recipe, but to understand the craft in a way that changes their practice. It answers the question \"can you tell me about…?\" Diátaxis places explanation at *cognition* + *acquisition*: propositional knowledge, in service of study.\n\nIts characteristic problem isn't being written badly — it's not being written at all. The *why* of a system ends up scattered through commit messages, review threads, and hallway conversations, because explanation has no obvious owner. Writing it down as a first-class document is most of the battle.\n\n## Check you're writing the right thing\n\n- The content is **facts consulted while working** — options, parameters, structures → `diataxis-reference`. The boundary test: reference serves the reader mid-work; explanation serves the reader who has stepped back. Lists and tables usually mean reference; \"tell me more about…\" means explanation.\n- The content **directs a task** → `diataxis-how-to`.\n- The content **teaches a beginner by doing** → `diataxis-tutorial`.\n- Mixed or unclear → step back to the `diataxis` router and run the compass.\n\n## Step 1 — Frame the \"about\"\n\nAn explanation's title carries an implicit *about*: \"About user authentication,\" \"On caching strategy,\" \"Why the scheduler is cooperative.\" Fix the topic and its altitude first:\n\n1. **Name the subject** as a topic, not a task.\n2. **Choose the bounds.** Explanation may range — history, alternatives, tradeoffs — but around a bounded subject. If the scope is \"everything,\" it's several articles.\n3. **Know the reader's question.** What understanding are they missing that this article supplies? Design decisions, constraints, and history the code can't show are the highest-value material.\n\n## Step 2 — Gather the why\n\nExplanation is the one type whose raw material is mostly *not* in the artifact. Mine where the reasoning actually lives: design docs, ADRs, commit messages, PR discussions, issue threads, the user's own memory. Interview the user for what nothing else records — \"why not the obvious alternative?\" is usually the most productive question. Then verify any claims about the current system against the current system.\n\n## Step 3 — Write it\n\nExplanation has permissions the other three types deny — use them:\n\n- **Make connections.** Link the subject to related topics, to the rest of the system, to things outside it entirely. Weaving fragments into a coherent web is the job.\n- **Provide context.** Design decisions, historical reasons, technical constraints, with concrete examples: \"The reason for x is because historically, y…\"\n- **Approach from multiple directions.** Explanation may circle its subject; analogy is a legitimate tool: \"An x in system y is analogous to a w in system z. However…\"\n- **Have opinions.** All human knowledge is invested with opinion, and explanation is where it's admitted: \"W is better than z, because…\" Weigh alternatives honestly: \"Some users prefer w (because z). This can be a good approach, but…\"\n- **Stay off the tools.** The reader is reflecting, not executing. The moment the prose says \"now run…\", it has drifted.\n\n## Step 4 — The drift checklist\n\nUse this on your own draft, and as the audit lens when the `diataxis` router sends an existing explanation here. An audit invocation runs only this step — skip Steps 1–3 and report findings without editing; edits wait for explicit confirmation — the router's gate, or the user's when invoked directly. The repair move is usually **relocation — or consolidation**.\n\n- Instruction or procedure creeping in → relocate to a how-to guide or tutorial; link.\n- Dry enumerations of options, parameters, structures → relocate to reference; link.\n- The inverse problem — explanatory fragments scattered across tutorials, how-tos, and reference entries elsewhere in the doc set → gather them *into* this article and leave links behind. Consolidation is explanation's distinctive audit move.\n- Opinion presented as neutral fact without the reasoning → either supply the why or mark the perspective.\n- Unbounded scope, three subjects in one article → split along topic lines.\n- Claims about the system that no longer match the system → verify and update; rationale docs go stale silently.\n\n## Things not to do\n\n- **Don't** instruct. No steps, no commands to run.\n- **Don't** turn into a catalog. Exhaustive facts belong in reference.\n- **Don't** feign neutrality. Reference must be neutral; explanation earns trust by showing its reasoning, alternatives and all.\n- **Don't** leave the why unwritten because it feels \"obvious to the team.\" That's exactly the knowledge that leaves when people do.\n",{"name":5,"description":7},"main","029bf6d49f3d270442ace55a01cccb40113f7efa","plugins\u002Fdocs\u002Fskills\u002Fdiataxis-explanation","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills","https:\u002F\u002Fgithub.com\u002Fesond","https:\u002F\u002Flinktr.ee\u002Fesond0","Serial pragmatist.\r\n\r\nCheck out my other repos at @hexagram-solutions! ","2026-11-07 00:00:12",{"source":8,"skillName":5,"commands":63,"prompt":73,"zipAvailable":74},[64,67,70],{"tool":65,"command":66},"npx","npx skills add esond\u002Fskills --skill diataxis-explanation",{"tool":68,"command":69},"bunx","bunx skills add esond\u002Fskills --skill diataxis-explanation",{"tool":71,"command":72},"pnpm","pnpm dlx skills add esond\u002Fskills --skill diataxis-explanation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs\u002Fskills\u002Fdiataxis-explanation\u002FSKILL.md",true,[76],{"path":77,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":80,"sourceHtmlUrl":81},"agents\u002Fopenai.yaml","REFERENCE","参考文档",123,"https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs\u002Fskills\u002Fdiataxis-explanation\u002Fagents\u002Fopenai.yaml",[83,108,132,157,168,202],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":49},"01M71FF0KCP66CRNT9AT1T18Z9","work-item-voice","Write or edit the user's issues in their own voice, in any work tracker — Jira, Linear, GitHub Issues, Azure DevOps. Covers features (new behavior), tasks (work that needs doing), and bugs (behavior that does not match expectation). Load this whenever the deliverable is an issue body, whether they say \"file a bug\", \"write a ticket\", \"draft a story\", \"create an issue for this\", \"turn this into a Jira\", \"write this up in Linear\", or paste a thread and ask for an issue out of it. Load it too whenever text goes into an issue that already exists — \"record this in the issue\", \"add what we found to the ticket\", \"note this on the card\", \"update the one about refunds\", or naming an issue by its key and asking for a fact to go in it — and when writing or updating one is a step inside a larger task. Features get behavior-driven framing with no implementation prescribed, and bugs get expected versus actual. Not for a comment on an issue, which is a conversation turn.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fesond\u002Fskills\u002Fwork-item-voice\u002FSKILL.md",[],[37,90,91,92,93,94,95,96,97,98,99,100,101,102,44,103,104,105,106,107],"work item voice","work item","voice","conversation","which","get","card","ticket","up","issues","new","writing","azure devops","ask","tasks","text","create","tracker",{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":117,"publishedAt":49},"01M71FETV1H7JPCTSKMW3XZV1T","conversational-voice","Write the user's side of a conversation with another person, in the user's own voice: Slack messages and replies, DMs, email, PR and code-review comments, Linear or Jira comments, and any other turn in an exchange that goes out under the user's name. Load this whenever the deliverable is a message a human will read as written by the user, whether they say \"draft a Slack message\", \"reply to this\", \"how should I word this\", \"tell the team\", \"ask them about X\", \"send a note to\", or just paste a thread and ask what to say back. Load it too when tightening, shortening, or sanity-checking a message they already wrote, and when a message is one step of a larger task. The register is direct and informal, the way they'd talk to a friend or acquaintance, with the answer up front for a reader who skims. Not for something the user authors rather than sends — an issue body, a PR description, a commit message — even though a person reads those too.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Fesond\u002Fskills\u002Fconversational-voice\u002FSKILL.md",[114],{"categoryNo":115,"categoryName":116,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000005","邮件与沟通",[118,92,119,93,120,121,98,122,44,103,123,124,125,126,127,128,129,130,131,35],"conversational voice","back","messages","send","slack messages","code","commit","team","code-review","review","sanity","message","slack","human",{"skillNo":133,"name":134,"nameZh":6,"description":135,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":136,"categories":137,"keywords":141,"publishedAt":49},"01M71FEN36NS9Y4RVX6KQ704TB","sync-core-repo-docs","Create or audit a repo's three core doc files — README.md, the agent instructions file (AGENTS.md or CLAUDE.md), and REVIEW.md — in that dependency order. If a file is missing, generate it from the codebase; if it exists, audit it against the current code and apply targeted fixes after confirmation. README.md gets a developer from clone to running the project; AGENTS.md captures coding guidance for the agent (delegating to \u002Finit or claude-md-improver); REVIEW.md holds guidance for code reviewers, human or automated, without duplicating AGENTS.md. Target files with --readme, --claude, and --review, or run all three. Use whenever the user wants to set up, bootstrap, scaffold, refresh, audit, update, or sync a repo's docs, or says things like \"create a README\", \"is my README still accurate\", \"write a CLAUDE.md\", \"write an AGENTS.md\", \"audit our docs\", or \"get this repo ready for contributors\" — even when only one file is named. Prefer it over claude-md-improver when README or REVIEW are also in scope.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Fsync-core-repo-docs\u002FSKILL.md",[138],{"categoryNo":139,"categoryName":140,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000030","开发工程师",[142,143,144,145,146,147,148,149,150,95,151,152,98,153,154,155,156,44,123,127],"sync","sync core repo docs","repo docs","core","repo","docs","agent instructions","SET","ready","scope","project","init","only","files","confirmation",{"skillNo":158,"name":159,"nameZh":6,"description":160,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":161,"categories":162,"keywords":163,"publishedAt":49},"01M71FEKJQ2G2NQ4NCXRR9SD63","sync-core-docs","Create or audit a repo's README.md, AGENTS.md\u002FCLAUDE.md, and REVIEW.md docs.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Fsync-core-docs\u002FSKILL.md",[],[164,147,145,142,106,165,166,34,167,146,127],"sync core docs","true","md docs","README",{"skillNo":169,"name":170,"nameZh":6,"description":171,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":172,"categories":173,"keywords":183,"publishedAt":49},"01M71FEAWPC8BM27EE0A90VT8T","righting-software-system-design","Opt-in, collaborative system-design workflow based on Juval Löwy's iDesign methodology in *Righting Software*. Conducts a multi-phase interview (framing → use cases → volatility analysis → components → call-chain validation → report) that surfaces unknown-unknowns and produces a written recommendation at `decompositions\u002F{system-name}\u002Freport.md`. **Run only when the user explicitly invites this workflow** — not for general architecture questions, lightweight design conversations, or quick \"where should X live?\" questions. Valid triggers: the user names the skill directly, references *Righting Software* \u002F Juval Löwy \u002F iDesign \u002F \"The Method\" \u002F volatility-based decomposition and asks to run a full session, asks for a \"deep\" or \"structured\" or \"Löwy-style\" system design session, or accepts a prior suggestion to run it. Wait for an explicit yes before entering Phase 0. The skill is interrogative — a back-and-forth interview that challenges each volatility candidate and proposes ones the user hasn't considered.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Frighting-software-system-design\u002FSKILL.md",[174,177,180],{"categoryNo":175,"categoryName":176,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":178,"categoryName":179,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":181,"categoryName":182,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000032","设计师",[184,45,185,186,187,188,189,190,191,192,193,194,43,195,196,197,198,199,200,201],"system design","software","system","righting software","righting software system design","deep","quick","wait for","unknown","components","candidate","phase","valid","run","at","wait","live","full",{"skillNo":203,"name":204,"nameZh":6,"description":205,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":206,"categories":207,"keywords":208,"publishedAt":49},"01M71FE4QYB436ZS8H3SWWHA4F","reorganize-branch-commits","Reorganize the commits on a non-default git branch into a clean, logical history by rewriting the branch — `git reset` + re-commit by default, `git rebase -i` when commit boundaries already align. Propose groupings based on the actual work done (features, refactors, tests, fixes, docs), get explicit user approval, back the branch up, then rewrite history. Use this skill whenever the user wants to tidy up, clean up, reorganize, restructure, squash, or curate commits on a feature branch — even if they phrase it as \"my branch is a mess\", \"squash this down\", \"combine these commits\", \"fix up the commit log before I open a PR\", or \"make the commits presentable for review\". Trigger proactively when the user is about to open or push a PR and the branch has scrappy\u002FWIP\u002F\"fix\" commits to collapse. Refuses to operate on default or release-shaped branches (main, master, develop, trunk, production, release, or the repo default) — a feature-branch-only tool.","https:\u002F\u002Fgithub.com\u002Fesond\u002Fskills\u002Fblob\u002Fmain\u002Fplugins\u002Feng\u002Fskills\u002Freorganize-branch-commits\u002FSKILL.md",[],[209,210,211,119,212,95,213,214,215,98,216,217,218,219,154,220,54,44,221,124],"branch","reorganize branch commits","commits","operate","align","re","default","fix","clean","branches","open","tidy","done"]