forked from
mitchellh.com/go-libghostty
Go bindings for libghostty-vt.
skills: add upstream-api-feedback skill
Adds an agent skill that reviews Go bindings against upstream
libghostty-vt C headers and produces concrete API improvement
suggestions. The skill applies a checklist of known friction
patterns (multi-call data fetching, ptr/len splits, repeated
parameter triples, two-phase init) and writes findings with
impact ratings and C signature sketches to UPSTREAM.md.
+148
+148
.agents/skills/upstream-api-feedback/SKILL.md
+148
.agents/skills/upstream-api-feedback/SKILL.md
···
1
+
---
2
+
name: upstream-api-feedback
3
+
description: >-
4
+
Reviews Go bindings against upstream libghostty-vt C headers and
5
+
produces concrete upstream API improvement suggestions. Use when
6
+
asked to review bindings for upstream feedback, suggest C API
7
+
changes, find API friction, or improve the upstream API.
8
+
---
9
+
10
+
# Upstream API Feedback
11
+
12
+
Analyzes the Go bindings in this project against the upstream
13
+
libghostty-vt C headers to identify concrete, actionable API
14
+
changes that would make the bindings more performant, idiomatic,
15
+
or easier to use. Output is written to directly to the chat.
16
+
17
+
## When to use
18
+
19
+
- The user asks for upstream API feedback or suggestions.
20
+
- The user asks to review bindings for performance or ergonomics.
21
+
- After binding a new API, to check for friction points.
22
+
23
+
## Workflow
24
+
25
+
### 1. Identify scope
26
+
27
+
Determine which bindings to review:
28
+
29
+
- **Specific file** (e.g. "review kitty_graphics.go"): Focus on
30
+
that file and its corresponding C header.
31
+
- **All bindings** (e.g. "review everything"): Scan all `*.go`
32
+
files (excluding `_test.go`) and cross-reference with headers.
33
+
- **Recent changes**: Use `jj diff` or `git diff` to find what
34
+
changed and focus on those files.
35
+
36
+
### 2. Read the Go bindings and C headers together
37
+
38
+
For each file in scope:
39
+
40
+
1. Read the Go file to understand the binding patterns used.
41
+
2. Read the corresponding C header in
42
+
`build/_deps/ghostty-src/zig-out/include/ghostty/vt/`.
43
+
3. Note every CGo crossing — each `C.ghostty_*()` call.
44
+
45
+
### 3. Apply the analysis checklist
46
+
47
+
For each API surface, check for these patterns:
48
+
49
+
#### Multi-call data fetching (highest impact)
50
+
51
+
Look for Go functions that make multiple `C.ghostty_*_get()` calls
52
+
to fetch logically related fields from the same object. Each CGo
53
+
call has ~100ns overhead that compounds in hot paths.
54
+
55
+
**Signal**: A Go type whose methods each call the same C
56
+
`_get(handle, ENUM_VARIANT, &out)` function with different enum
57
+
values — especially when callers typically need several fields
58
+
together.
59
+
60
+
**Suggestion**: A sized struct (like `GhosttyRenderStateColors`)
61
+
that returns all fields in a single call. Reference the existing
62
+
`GHOSTTY_INIT_SIZED` pattern.
63
+
64
+
#### Pointer/length splits
65
+
66
+
Look for cases where pointer and length are separate enum variants
67
+
in the same `_get()` API (e.g. `DATA_PTR` + `DATA_LEN`). These
68
+
are semantically one value split across two calls.
69
+
70
+
**Signal**: The Go binding must make two sequential calls and has
71
+
no atomicity guarantee between them.
72
+
73
+
**Suggestion**: Either fold into the sized struct above, use
74
+
`GhosttyString`-style `{ptr, len}` as a single variant, or add a
75
+
dedicated function.
76
+
77
+
#### Repeated parameter triples
78
+
79
+
Look for multiple C functions that take the same parameter
80
+
combination (e.g. `(iterator, image, terminal)`) and are typically
81
+
called together per iteration step.
82
+
83
+
**Signal**: The Go code calls 3-4 functions with identical
84
+
arguments in sequence during a loop body.
85
+
86
+
**Suggestion**: A combined function returning a struct with all
87
+
results, cutting N CGo crossings to 1.
88
+
89
+
#### Two-phase initialization
90
+
91
+
Look for patterns where an object must be allocated, then populated
92
+
via a separate call before it's usable (e.g. `_new()` then
93
+
`_get(POPULATE, &handle)`).
94
+
95
+
**Signal**: The Go binding wraps this in a helper but the C API
96
+
still requires two calls where one would suffice.
97
+
98
+
**Suggestion**: A combined constructor, or making the populate step
99
+
part of `_new()`.
100
+
101
+
#### Missing convenience variants
102
+
103
+
Look for C APIs that could offer a simpler overload for the common
104
+
case while keeping the flexible version.
105
+
106
+
**Signal**: The Go binding wraps a complex C API with a simpler Go
107
+
function that most callers use, hiding parameters that are almost
108
+
always the same value.
109
+
110
+
**Suggestion**: A C convenience function for the common case.
111
+
112
+
### 4. Assess impact
113
+
114
+
Rate each suggestion:
115
+
116
+
- **Hot path**: Called per-frame or per-placement in a render loop.
117
+
CGo overhead is multiplied by iteration count. High impact.
118
+
- **Setup path**: Called once during initialization or
119
+
configuration. Low impact — ergonomics matter more than perf.
120
+
- **Ergonomic**: Doesn't affect performance but makes the API
121
+
harder to use correctly or requires awkward binding code.
122
+
123
+
### 5. Write the output
124
+
125
+
Write findings to chat. Format:
126
+
127
+
```markdown
128
+
# Upstream API Feedback
129
+
130
+
Summary of the review scope and methodology.
131
+
132
+
## Suggestion Title
133
+
134
+
**Impact**: Hot path / Setup path / Ergonomic
135
+
**Files**: `header.h`, `binding.go`
136
+
137
+
Description of the current pattern, why it's suboptimal, and the
138
+
concrete C API change. Include a struct/function signature sketch.
139
+
140
+
## Next Suggestion
141
+
142
+
...
143
+
```
144
+
145
+
Group suggestions by impact (hot path first). Include concrete C
146
+
type/function signatures — not vague ideas. Reference existing
147
+
libghostty-vt patterns (like `GhosttyRenderStateColors`) as
148
+
precedent when applicable.