home / skills / lookatitude / beluga-ai / doc-writing

doc-writing skill

safe

This skill assists you write Go package docs and tutorials with structured patterns, examples, and clear guidance for Beluga AI v2.

npx playbooks add skill lookatitude/beluga-ai --skill doc-writing

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.4 KB

---
name: doc-writing
description: Documentation writing patterns for Beluga AI v2. Use when creating package docs, tutorials, API guides, or teaching-oriented content.
---

# 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/...`).
- 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.

Overview

This skill provides documentation-writing patterns and a reproducible structure for Beluga AI v2 packages. It codifies headers, quick-starts, interfaces, examples, configuration, and extension guidance so authors produce consistent, compile-ready Go docs. Use it when creating package docs, tutorials, API guides, or teaching-oriented content.

How this skill works

The skill inspects the target package surface and enforces a standard doc layout: header, minimal working example, core interface, usage examples, configuration options, and an extension guide. It validates that every concept includes a complete, compilable code snippet with full import paths, explicit error handling, and cross-references to related docs. It flags marketing language, filler text, and incomplete examples.

When to use it

Authoring a new package README or package-level Go doc for Beluga AI v2.
Writing quick-starts and minimal examples that must compile out of the box.
Creating tutorials with progressive complexity: basic, intermediate, advanced.
Documenting configuration options and exportable WithX() functional options.
Guiding contributors on extending interfaces and registering implementations.

Best practices

Start with one-paragraph header: what it does, who uses it, why.
Include a 3–10 line minimal working example with full import paths.
Show every concept with a compiling code example and explicit error handling.
List core interfaces and provide usage variants: basic, middleware, hooks, custom impl.
Document all WithX() options with defaults and examples of common combinations.
Link to docs/providers.md and related package docs; avoid duplicating architecture content.

Example use cases

Create a package doc that includes a quick-start code snippet importing github.com/lookatitude/beluga-ai/... so users copy-paste a compiling example.
Write a tutorial with three sections: basic (5min), intermediate (10min), advanced (15min) showing progressive features.
Document a new extensible interface, include an example implementation, register it via init(), map its errors, and add tests.
Produce an API guide that enumerates WithX() configuration options with defaults and usage patterns.
Convert ad-hoc examples into explicit, error-checked snippets that compile and reference docs/providers.md for provider details.

FAQ

Must every example compile?

Yes. Provide full import paths and explicit error handling; do not use blank identifier for errors.

Where to list providers?

Point readers to docs/providers.md rather than enumerating providers in each package doc.