writing-commentary

$npx mdskill add supabase/supabase-go/writing-commentary

The following documents will be helpful:

SKILL.md

.github/skills/writing-commentaryView on GitHub ↗
---
name: writing-commentary
description: Guides the content and style of all comments - Go doc comments on exported or internal identifiers, package overviews in doc.go, inline comments and comments in scripts, workflows, SQL and configuration files. Use when writing, editing or reviewing any comment on any surface, including comments authored in passing while implementing something else. Covers audience focus (API consumer versus codebase maintainer), contract-first phrasing and where rationale, history and cross-component notes belong instead.
---

The following documents will be helpful:

| Document | For |
| -------- | --- |
| [`DEVELOPMENT.md`](../../../DEVELOPMENT.md) | The Commentary section defining the normative rules for what any comment may say. For example: contract not rationale, self-contained at its boundary, no language tutoring, no roadmap narration, each fact stated once at the site that owns it. |
| [`decisions.md`](../../../decisions.md) | The destination for the "why" that comments must not carry: rationale, alternatives considered and history live there as What+Why records. |
| [`standard.md`](../../../standard.md) | The requirement that every exported identifier carries a Go-idiomatic doc comment with runnable examples where apt - the coverage rule that the Commentary section's content rules complement. |

When removing why-content from an existing comment, check whether [`decisions.md`](../../../decisions.md) already records it and move it there in the same change if not.

## Supabase Writing Skill

Defines the writing style to use, sometimes referred to as the "Supabase voice".

Available as a shared, internal skill (at the time of writing this, it is not open source or otherwise public).
Defines style guide rules, bans AI writing patterns, and sets the documentation tone.

If this is available to you then you must use it.

### Arbitrary Limits

The writing skill might define a maximum quantity of some concept in the writing, for example:

- the number of links allowed on a 'page'
- the number of bullets allowed in a list
- the number of characters allowed in a 'post'

These limits are usually arbitrary and subjective, applying to other content types rather than API commentary. Also, often the concept of a 'page' is difficult or impossible to define in this commentary writing context. For this reason, when you come across such limits, ignore them.

More from supabase/supabase-go

SkillDescription
auditing-tool-currencyGuides auditing the repository's externally sourced, version-pinned tooling against canonical origins - the GitHub Actions pins, the Go tool module under tools/go, the npm tool module under tools/node, the pinned Supabase CLI and the Go consumer floor. Use when asked which tools could be upgraded, whether pins are stale or to prepare an upgrade report or plan. Audit and report only: applying a bump is the changing-build-and-continuous-integration skill's territory.
changing-build-and-continuous-integrationGuides changes to this repository's build, module and CI machinery rather than the SDK's own code. Use when touching any go.mod, the go.work workspace, the scripts folder, GitHub Actions workflows, the pinned tool modules under tools or the spell-check configuration - including adding a new module, taking on a new dependency or bumping a Go or tool version. Covers workspace wiring for unpublished sibling modules, the published Go version floor versus the CI toolchain, digest pinning, the first-party-actions-only policy and the rule that CI jobs run the same scripts developers run locally.
designing-internal-boundariesGuides the design of internal type contracts in respect of immutability and encapsulation. Enhances codebase maintainability by separating concerns in a manner that is compiler-enforced, both for internal state as well as immutable values returned to callers alike. Use when creating or reworking types, when adding machinery (e.g. parsing, caching, transport, crypto), when naming or splitting an internal package, when writing constructors or defensive copies and when deciding whether a test is external or in-package.
designing-public-interfacesGuides design of this SDK's public API surface. Use when adding, renaming, removing or reshaping any exported identifier in any module published as end-user, consumer-facing interface - whether that module be existing or new to the published surface area. Includes functional options, domain client accessors, error model, sentinel errors, error struct types, exported fields, the accessor pattern, constructor signatures and naming policy.
recording-decisionsGuides when a development decision earns a decisions.md entry and how entries are proposed and written. Use when a design choice is made, changed or reverted during any task. Never write decisions.md unprompted - a candidate entry is proposed in chat through the three-part falsification test (maintainer question, answer-from-source attempt, why the answer fails) and only a commissioned entry is written. Covers the false-trigger list and the What/Why authoring rules.
writing-changelogsGuides the writing and editing of changelog entries in the per-module CHANGELOG.md files. Use when a user-facing change needs an entry, when drafting or reshaping an Unreleased section, or when reviewing entries at release time. Covers the type headings, the entry shape and the succinctness bar - what an entry says and what it leaves to the docs.
writing-examplesGuides the creation, update, merging and deletion of examples - the runnable Example functions that render on pkg.go.dev, the code snippets inside doc comments and the example programs under examples/. Use when adding an example, reworking one or deciding whether an existing example is replaced, upgraded, folded into a sibling or removed outright. Covers the removal test and when an example earns its place.