Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/enitrat/skill-issue --skill sdk-documentationAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
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
