My own corner of monopam
mdx skill: document the open <Pkg> convention for in-package examples
Captures the rule the recent ocaml-claude .mli changes converged on:
when a .mli lives inside package `Foo` and uses many `Foo.X` /
`Foo.Y` references, `open Foo` at the top of the block reads better
than peppering the prefix on every call site.
Distinguishes packages whose top-level module groups several
sub-modules a typical example uses together (Claude, Irmin) -- where
the open is helpful -- from single-dominant-module packages
(Toml, Sse) where the qualified form is already short.
+35
+35
ocaml-claude-skills/plugins/monopam/skills/mdx/SKILL.md
+35
ocaml-claude-skills/plugins/monopam/skills/mdx/SKILL.md
···
163
163
provides which name — the example documents both the call and
164
164
the import surface, and both must be obvious.
165
165
166
+
### Inside the documenting package, prefer `open <Pkg>` once
167
+
168
+
When a `.mli` lives inside package `Foo` and the example uses
169
+
many `Foo.X` / `Foo.Y` references, `open Foo` at the top of the
170
+
block is cleaner than peppering the same prefix on every line.
171
+
The reader still sees the import surface (`open Foo`) and reads
172
+
short call sites:
173
+
174
+
```ocaml
175
+
(** Prefer:
176
+
{[
177
+
open Claude
178
+
179
+
let cfg =
180
+
Options.default
181
+
|> Options.with_model `Sonnet_4_5
182
+
|> Options.with_permission_mode Permissions.Mode.Accept_edits
183
+
]} *)
184
+
185
+
(** Avoid: deeply prefixed where every line repeats the package name.
186
+
{[
187
+
let cfg =
188
+
Claude.Options.default
189
+
|> Claude.Options.with_model `Sonnet_4_5
190
+
|> Claude.Options.with_permission_mode
191
+
Claude.Permissions.Mode.Accept_edits
192
+
]} *)
193
+
```
194
+
195
+
This applies to packages whose top-level module groups several
196
+
sub-modules a typical example uses together (`Claude`, `Irmin`,
197
+
`Cmdliner`). It does not apply to packages with a single dominant
198
+
module — in those, the qualified form is already short
199
+
(`Toml.parse`, `Sse.Parser.create`).
200
+
166
201
## Determinism
167
202
168
203
Examples must produce the same output every run on every machine: