[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AMVBP2P2HRH7SF11MAH4KP":3,"skill-same:01M7AMVBP2P2HRH7SF11MAH4KP":48},{"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":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7AMVBP2P2HRH7SF11MAH4KP","devex-api-sdk-and-docs",null,"Use when designing an API or SDK a developer will call, or writing and restructuring the documentation they read: method placement and discoverability, consistency, defaults, autocomplete, time-to-first-call, idempotency keys, API versioning and deprecation policy, Diataxis (tutorial, how-to, reference, explanation), README first screen, executable docs tested in CI, docs style, and docs feedback. Triggers on API usability, SDK design, time to first call, Stripe-style versioning, deprecation, Diataxis, README, docs-as-code. Companion to the other developer-experience skills.","the-vibey-project\u002Fvibey","the-vibey-project","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F329298758?v=4","01M7AJHGZ9722CTJ4JNQZVRH0Q","the vibey project","01M7AJHGZVMG2K7TGXQ6XFHVG3",5,"MIT","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fdeveloper-experience\u002Fskills\u002Fdevex-api-sdk-and-docs\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: devex-api-sdk-and-docs\ndescription: \"Use when designing an API or SDK a developer will call, or writing and restructuring the documentation they read: method placement and discoverability, consistency, defaults, autocomplete, time-to-first-call, idempotency keys, API versioning and deprecation policy, Diataxis (tutorial, how-to, reference, explanation), README first screen, executable docs tested in CI, docs style, and docs feedback. Triggers on API usability, SDK design, time to first call, Stripe-style versioning, deprecation, Diataxis, README, docs-as-code. Companion to the other developer-experience skills.\"\n---\n\n# Developer Experience: API and SDK Design, and Documentation\n\n> **Part 3 of 9** of the *Developer Experience Blueprint* (plugin `developer-experience`), covering: API and SDK design; Documentation. Sibling skills: `devex-principles-and-feedback-loops`, `devex-cli-and-errors`, `devex-interfaces-onboarding-and-agents`, `devex-surface-placement`, `devex-editor-and-desktop-surfaces`, `devex-mobile-and-web-surfaces`, `devex-non-developers-and-visual-design`, `devex-reference`. A reference into a sibling is written *Section name → `skill`*.\n>\n> **Currency:** the blueprint is dated Oct 23, 2026; its evidence base and the AI-tooling claims age fastest, so re-check those first.\n>\n> Evidence grades used throughout: **A** = peer-reviewed or large study, **B** = credible practitioner or single study, **C** = vendor or opinion. Thin evidence is flagged where it occurs, and collected under *Where the evidence is weak or conflicting* in `devex-reference`.\n\n## API and SDK design\n\nThe strongest evidence here is experimental: in Myers & Stylos's usability studies, finding a method was 2.4 to 11.2 times faster when it sat on the object developers expected, and requiring a factory or helper object slowed people down. Robillard & DeLine found documentation to be a top obstacle in learning APIs.\n\n- **Put methods where people look.** Place the action on the type that owns the data; test placement with a quick think-aloud study of five developers.\n- **Be consistent.** Same verb, same argument order, same error shape everywhere.\n- **Make the default work.** The one-line call should do the common thing; options are additive.\n- **Optimize for autocomplete.** Descriptive names, typed parameters, and doc comments that appear in the editor.\n- **Design time-to-first-call.** Track how long a new user takes to make a successful request; the [Nordic APIs write-up](https:\u002F\u002Fnordicapis.com\u002Fwhy-time-to-first-call-is-a-vital-api-metric\u002F) explains the metric.\n- **Make writes safe to retry.** Idempotency keys, as Stripe does.\n- **Version deliberately.** [Stripe's date-based versioning](https:\u002F\u002Fstripe.com\u002Fblog\u002Fapi-versioning) pins each account to the version it started on and lets it upgrade on its own schedule; whatever scheme you pick, publish it.\n- **Deprecate with notice.** Announce, warn at runtime with a link to the migration guide, give a dated removal window, and keep a changelog readers can subscribe to.\n- **Combine two review methods.** Heuristic evaluation and think-aloud testing found mostly independent problems, so neither replaces the other.\n\n## Documentation\n\nSplit docs by the reader's need, lead with something that runs, and keep examples tested.\n\n| Type | Reader's question | Rule |\n| --- | --- | --- |\n| Tutorial | \"Teach me\" | One guided path to a working result in minutes; no choices |\n| How-to guide | \"Help me do X\" | Steps for one goal; assumes basic knowledge |\n| Reference | \"What exactly is X?\" | Complete, accurate, generated from code where possible |\n| Explanation | \"Why is it this way?\" | Background and trade-offs; no steps |\n\nThis is the Diátaxis model. I read it only through secondary sources (the diataxis.fr site could not be fetched), and its value rests on practitioner adoption rather than controlled studies.\n\n- **README first screen:** what it is, one install command, one runnable example, where to go next.\n- **Executable docs:** run code samples in CI (doctests, or snippet tests) so examples never rot.\n- **Style:** second person, active voice, present tense, one idea per sentence, descriptive link text (Google's developer documentation style guide is the usual reference).\n- **Search and navigation:** every page answers one question, has a stable URL and links to the next step.\n- **Versioning:** docs match the released version, with a clear switcher.\n- **Feedback:** a visible \"was this useful\" control and an edit link that goes straight to a pull request.\n- **Copy-paste friendly:** commands without prompt characters, and sample output shown separately.\n","# Developer Experience: API and SDK Design, and Documentation\n\n> **Part 3 of 9** of the *Developer Experience Blueprint* (plugin `developer-experience`), covering: API and SDK design; Documentation. Sibling skills: `devex-principles-and-feedback-loops`, `devex-cli-and-errors`, `devex-interfaces-onboarding-and-agents`, `devex-surface-placement`, `devex-editor-and-desktop-surfaces`, `devex-mobile-and-web-surfaces`, `devex-non-developers-and-visual-design`, `devex-reference`. A reference into a sibling is written *Section name → `skill`*.\n>\n> **Currency:** the blueprint is dated Oct 23, 2026; its evidence base and the AI-tooling claims age fastest, so re-check those first.\n>\n> Evidence grades used throughout: **A** = peer-reviewed or large study, **B** = credible practitioner or single study, **C** = vendor or opinion. Thin evidence is flagged where it occurs, and collected under *Where the evidence is weak or conflicting* in `devex-reference`.\n\n## API and SDK design\n\nThe strongest evidence here is experimental: in Myers & Stylos's usability studies, finding a method was 2.4 to 11.2 times faster when it sat on the object developers expected, and requiring a factory or helper object slowed people down. Robillard & DeLine found documentation to be a top obstacle in learning APIs.\n\n- **Put methods where people look.** Place the action on the type that owns the data; test placement with a quick think-aloud study of five developers.\n- **Be consistent.** Same verb, same argument order, same error shape everywhere.\n- **Make the default work.** The one-line call should do the common thing; options are additive.\n- **Optimize for autocomplete.** Descriptive names, typed parameters, and doc comments that appear in the editor.\n- **Design time-to-first-call.** Track how long a new user takes to make a successful request; the [Nordic APIs write-up](https:\u002F\u002Fnordicapis.com\u002Fwhy-time-to-first-call-is-a-vital-api-metric\u002F) explains the metric.\n- **Make writes safe to retry.** Idempotency keys, as Stripe does.\n- **Version deliberately.** [Stripe's date-based versioning](https:\u002F\u002Fstripe.com\u002Fblog\u002Fapi-versioning) pins each account to the version it started on and lets it upgrade on its own schedule; whatever scheme you pick, publish it.\n- **Deprecate with notice.** Announce, warn at runtime with a link to the migration guide, give a dated removal window, and keep a changelog readers can subscribe to.\n- **Combine two review methods.** Heuristic evaluation and think-aloud testing found mostly independent problems, so neither replaces the other.\n\n## Documentation\n\nSplit docs by the reader's need, lead with something that runs, and keep examples tested.\n\n| Type | Reader's question | Rule |\n| --- | --- | --- |\n| Tutorial | \"Teach me\" | One guided path to a working result in minutes; no choices |\n| How-to guide | \"Help me do X\" | Steps for one goal; assumes basic knowledge |\n| Reference | \"What exactly is X?\" | Complete, accurate, generated from code where possible |\n| Explanation | \"Why is it this way?\" | Background and trade-offs; no steps |\n\nThis is the Diátaxis model. I read it only through secondary sources (the diataxis.fr site could not be fetched), and its value rests on practitioner adoption rather than controlled studies.\n\n- **README first screen:** what it is, one install command, one runnable example, where to go next.\n- **Executable docs:** run code samples in CI (doctests, or snippet tests) so examples never rot.\n- **Style:** second person, active voice, present tense, one idea per sentence, descriptive link text (Google's developer documentation style guide is the usual reference).\n- **Search and navigation:** every page answers one question, has a stable URL and links to the next step.\n- **Versioning:** docs match the released version, with a clear switcher.\n- **Feedback:** a visible \"was this useful\" control and an edit link that goes straight to a pull request.\n- **Copy-paste friendly:** commands without prompt characters, and sample output shown separately.\n",{"name":5,"description":7},"develop","ae32736a1aabddabca5d2c96d665aa0ebc7d8700","src\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fdeveloper-experience\u002Fskills\u002Fdevex-api-sdk-and-docs",3,"https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey","https:\u002F\u002Fthe-vibey-project.github.io\u002Fvibey\u002F","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project","https:\u002F\u002Fvibewithadam.matthewsteinberger.com","freedom for software engineers","2026-11-15 05:47:42",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add the-vibey-project\u002Fvibey --skill devex-api-sdk-and-docs",{"tool":40,"command":41},"bunx","bunx skills add the-vibey-project\u002Fvibey --skill devex-api-sdk-and-docs",{"tool":43,"command":44},"pnpm","pnpm dlx skills add the-vibey-project\u002Fvibey --skill devex-api-sdk-and-docs","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fdeveloper-experience\u002Fskills\u002Fdevex-api-sdk-and-docs\u002FSKILL.md",true,[],[49,56,63,70,77,84],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7AT1FQJAE1FQYAMDTF490Y4","white-paper-writing","Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks \"how should I structure this\" for a long-form document.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fwhite-paper-writing\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7AT16BJRJJKK2MASXRZS76G","prose-technical-mechanics","Use when editing or writing prose at a technical\u002Fmechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-technical-mechanics\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7AT0W9HT0ZZ9Y287NW99MR3","prose-mechanics","Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate\u002FJamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix \"AI-sounding\" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-mechanics\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M7AT0KR635JX66X2X6F3E2CP","narrative-structure","Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or \"how should I structure this story\u002Fpitch\u002Fpresentation\" request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fnarrative-structure\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7AT0AKGW09NKKZDYBT8VRDE","legal-brief-writing","Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic\u002Fneurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Flegal-brief-writing\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7AT00VWPS4Q8B5VEMXX9NQT","journal-publishability-criteria","Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs\u002Fpaper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fjournal-publishability-criteria\u002FSKILL.md",[],[]]