writing-commentary
Skill10 starsChanged 44 days agoMITView on GitHub
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.
In this repository7 other files it gives its agents.
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
When removing why-content from an existing comment, check whether decisions.md already records it and move it there in the same change if …
- Distinctive: line 23
If this is available to you then you must use it.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
The following documents will be helpful:
| Document | For |
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 | The destination for the "why" that comments must not carry: rationale, alternatives considered and history live there as What+Why records. |
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. Frozen: consult it, never edit it (see DEVELOPMENT.md). |
When removing why-content from an existing comment, check whether 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.