Agent Skills: Documentation Patterns

Documentation Patterns

Package Doc Structure

1. Header: One paragraph — what it does, who uses it, why.
2. Quick Start: Minimal working example (3-10 lines), full imports, compiles.
3. Core Interface: Go interface definition.
4. Usage Examples: Basic, with middleware, with hooks, custom implementation.
5. Configuration: All WithX() options with defaults.
6. Extension Guide: Implement interface → register via init() → map errors → write tests.

Rules

• Every concept needs a code example.
• Examples must compile with full import paths (github.com/lookatitude/beluga-ai/v2/...).
• Handle errors explicitly — never _ for error returns.
• No marketing language, filler words, or emojis.
• Professional, active voice, present tense, imperative for instructions.
• Cross-reference related packages and docs/.
• Use mermaid diagrams sparingly (< 15 nodes).
• Tutorials: progressive complexity (basic 5min, intermediate 10min, advanced 15min).

Don'ts

• No phase references or timeline language.
• Don't duplicate architecture docs — link to them.
• Don't list every provider — point to docs/providers.md.
• Don't show incomplete examples that won't compile.