writing-examples
Skill10 starsChanged 44 days agoMITView on GitHub
Guides 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.
In this repository7 other files it gives its agents.
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are 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.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
When a removal leaves one suffixed example standing alone, the suffix distinguishes nothing and the survivor takes the plain name.
≈ “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 |
standard.md | The coverage requirement: runnable Example functions accompany doc comments where apt, compiled and verified by go test. Frozen: consult it, never edit it (see DEVELOPMENT.md). |
DEVELOPMENT.md | The Commentary section's exception letting a runnable example frame a convention that signatures cannot show. |
decisions.md | The records "Placeholder credentials in rendered examples name the real key type" and "Example programs are non-published modules run by the integration tier". |
The doc comment on an example is a comment like any other, owned by the writing-commentary skill.
The Removal Test
An example is removed, as the codebase evolves and other examples come in, when it does one of these:
- Scaffolding: It shows only that construction succeeds, which every other example in its package does as its first line.
- Test-shaped: It asserts behavior that the doc comment already states and a unit test already covers, and nothing in it shows a caller what to do.
- Superseded: A later, more mature example shows the same thing better.
- Near-duplicate: Its code matches a neighbor's except for one call.
An example stays when it shows a distinct decision, a convention that signatures cannot show or the basic read on one of the two entry routes.
Replacing and Upgrading
- Fold a near-duplicate into the sibling a reader reaches first, which keeps that sibling's name.
- When a removal leaves one suffixed example standing alone, the suffix distinguishes nothing and the survivor takes the plain name.
- go vet requires an example's name to map to a declared identifier, and an example's explanation sits in its doc comment rather than its body, because pkg.go.dev renders the doc comment as prose above the code.
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.