Agent skill
sdk-documentation
Rules and patterns for writing comprehensive, high-quality SDK documentation for public libraries. Covers documentation architecture, narrative tone, user guides, and API references. Use when: (1) Writing or reviewing documentation for a public SDK/library, (2) Creating API reference pages for hooks/functions/classes, (3) Writing getting-started guides or tutorials, (4) Structuring a documentation site from scratch, (5) Reviewing documentation quality and consistency, (6) Setting up a VitePress or GitBook documentation site for an SDK.
Install this agent skill to your Project
npx add-skill https://github.com/enitrat/skill-issue/tree/main/plugins/personal-skills/skills/sdk-documentation
SKILL.md
SDK Documentation Best Practices
Rules for writing clear, scannable, code-forward documentation for public SDKs. Derived from analysis of best-in-class SDK documentation (wagmi, viem, TanStack). Rules are domain-agnostic; examples use generic SDK patterns with occasional web3 illustrations.
Documentation Type Router
Before writing, identify which type of page you're creating. Each type has different rules.
| Question you're answering | Doc type | Template | Key rule |
|---|---|---|---|
| "Help me learn this SDK" | Tutorial (Getting Started) | guides.md → Tutorials | Learning-oriented: guide the reader, eliminate choices, show destination early |
| "Help me accomplish X" | How-to Guide (Task Guide) | guides.md → How-to Guides | Task-oriented: assume competence, action-only, address real-world complexity |
| "What does X do / accept / return?" | API Reference | api-reference.md | Information-oriented: describe only, zero explanation, mirror product structure |
| "Why does X work this way?" | Explanation (Concept/Why page) | tone.md → Explanation Pages | Understanding-oriented: provide context, make connections, admit tradeoffs |
The cardinal sin is mixing types. A tutorial that stops to explain architecture loses the learner. A reference page that teaches loses the practitioner looking up a parameter. An explanation page that includes step-by-step instructions belongs in a how-to guide.
Core Philosophy
| Principle | Meaning |
|---|---|
| Code is the star | Prose exists to introduce, contextualize, and connect code examples |
| Scannable over narrative | Readers skim for answers; structure for rapid lookup |
| Show, don't tell | Diff annotations and working examples beat explanations |
| One concept per step | Never introduce multiple ideas simultaneously |
| Full files, not snippets | Every code block should be runnable in isolation |
| Template rigidly | Predictable structure is a feature, not a limitation |
Quick Reference: Critical Rules
| Category | DO | DON'T |
|---|---|---|
| Voice | "you" for concepts, "we" for tutorials | Passive voice |
| Tone | Professional-casual, confident | Humorous, condescending, or stiff |
| Sentences | 10-25 words, active voice | 35+ word run-on sentences |
| Code examples | Complete runnable files with focus annotations | Partial snippets missing context |
| Parameters | One ### heading per param with full example |
Tables or lists of parameters |
| Optional params | Indicate via | undefined in type |
"Optional" badges or markers |
| Jargon | SDK-specific terms explained; ecosystem terms assumed | Over-explaining industry basics |
| Sections | Rigid ordering: Import → Usage → Parameters → Return Type | Freeform section ordering |
| Cross-refs | Link to related APIs inline and in dedicated sections | "See also" dump at bottom |
| Warnings | Use a warning admonition for critical info (see your framework's syntax) | Inline bold warnings in prose |
Detailed Guidance by Topic
- Documentation structure: See references/structure.md for site architecture, page templates, navigation, shared content systems
- Narrative tone & explanation pages: See references/tone.md for voice, style, sentence patterns, jargon handling, and explanation/concept page guidance
- Tutorials & how-to guides: See references/guides.md for tutorial rules (learning-oriented), how-to guide rules (task-oriented), progressive disclosure, framework variants
- API references: See references/api-reference.md for parameter docs, return types, TypeScript presentation, cross-referencing
- VitePress setup: See references/vitepress.md for project init, config, markdown extensions, twoslash, code groups, shared includes
- GitBook setup: See references/gitbook.md for Git Sync, content blocks, steppers, OpenAPI integration, reusable content
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
enitrat/skill-issue
tdd
Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
enitrat/skill-issue
super-ralph
Build multi-phase AI development pipelines with the Smithers workflow engine (v0.8.2). Use when: (1) Setting up a SuperRalph workflow for a repo (focuses, focusDirs, focusTestSuites, agents) (2) Debugging a run (ticket explosion, duplicate tickets, stalled nodes) (3) Understanding the pipeline phases and what generates tickets (4) Avoiding common configuration mistakes that cause runaway ticket counts
enitrat/skill-issue
prd-authoring
enitrat/skill-issue
tanstack-best-practices
Best practices for building hook libraries with TanStack Query. Use when: (1) Writing useQuery/useMutation hooks that wrap async data-fetching functions, (2) Designing query key schemas and cache identity systems, (3) Building framework-agnostic query options factories, (4) Implementing cache invalidation patterns (invalidate vs remove vs setQueryData), (5) Wrapping TanStack Query in a multi-layered library (core actions to query options to framework hooks), (6) Handling non-serializable values (bigint, class instances) in query keys, (7) Bridging external stores (zustand, signals) with TanStack Query reactivity. Derived from wagmi's production architecture (React/Vue/Solid Ethereum hooks).
enitrat/skill-issue
smithers
Build multi-phase AI development pipelines with the Smithers workflow engine (v0.8.2). Use when: (1) Initializing a new Smithers project in a target directory (use the init CLI) (2) Adding phases or steps to existing workflows (3) Implementing review loops, pass tracking, or phase gating (4) Debugging workflow orchestration issues (Ralph loops, ctx.output, data threading) (5) Writing instruction MDX files for project configs (6) Configuring agents or per-role overrides
enitrat/skill-issue
effect-best-practices
Enforces Effect-TS patterns for services, errors, layers, and atoms. Use when writing code with Effect.Service, Schema.TaggedError, Layer composition, or effect-atom React components.
Didn't find tool you were looking for?