iterm-release
Skill1 starsChanged 5 months agoMITView on GitHub
Read a new iTerm2 release against the surfaces beacon renders through (layout prefs, dynamic profile keys, OSC controls, profile loading, Apple Events) and say whether beacon is affected. Use when iTerm2 ships a release, when the user asks whether an iTerm2 update breaks beacon, or when `just iterm-release` reports releases to read.
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 15
Run the script, not the recipe: the recipe's - prefix turns every exit into 0, and the exit is how this step reads the result.
- Distinctive: line 81
Only after the user agrees with the read:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Read an iTerm2 release
dev/iterm-release.py (just iterm-release) fetches the iTerm2 clone, lands it
on the newest release tag, and scans the diff since the version recorded in
dev/iterm-reviewed.json for the symbols beacon depends on. The scan is a
filter, not a verdict. This skill is the read that follows it.
1. Run the scan
Run the script, not the recipe: the recipe's - prefix turns every exit into
0, and the exit is how this step reads the result.
python3 dev/iterm-release.py- Exit 0 with "has been read": nothing to do. Report that and stop.
- Exit 2: a precondition failed (no clone, dirty clone, no recorded version). Surface the message as printed; don't work around it.
- Exit 1: releases are pending. Note the range (
vA..vB), the clone path, and every surface marked✗with the files it names.
On the first run the clone moves to the newest tag. If a re-run is needed, pass
--no-checkout. The clone is $ITERM2_SRC, else ~/src/github/gnachman/iTerm2.
The scan's symbols come from beacon's own sources (RECOMMENDED_LAYOUT and
RESET_FAMILIES in bin/beacon-iterm, the keys in
iterm/profile.json.template), so a key dropped from a table drops from the
watch in the same edit. A preference can be a string literal in
iTermPreferences.m or a DEFINE_FLOAT(name, default, …) in
iTermAdvancedSettingsModel.m, where the literal form never appears.
2. Read the notes
For each pending release, read docs/notes-<version>.txt in the clone. When
the report says (no notes file), the release's notes are still accumulating
in docs/notes-<major>.<minor>.txt: read its diff over the range instead.
git -C <clone> diff <range> -- docs/notes-<major>.<minor>.txt3. Read the commits
git -C <clone> log --oneline --no-merges <range>Pick out every commit that could touch a surface beacon paints (SPEC §4.1):
tab color and label, window title and session name, status bar, badge, dynamic
profiles and their loading, OSC 8 links, SetUserVar / SetColors /
SetProfile, AppleScript select / activate, tab-bar layout.
For each, git -C <clone> show --stat <sha> and read the message.
Then check the one class the scan can't judge from a hit alone: a changed
default. Look at the range's diff of the preference files and compare any
DEFINE_* second argument or iTermPreferences.m default against what
RECOMMENDED_LAYOUT in bin/beacon-iterm is tuned for.
git -C <clone> diff <range> -- sources/Settings/iTermAdvancedSettingsModel.m sources/Settings/iTermPreferences.mFor each ✗ surface from step 1, read the hunk that matched and decide whether
it changes what beacon writes or what iTerm2 does with it.
4. Report
Lead with the verdict: affected or not. Then a table of the commits that touch a beacon surface only (sha, what changed, what it means for beacon), and one line naming the areas the rest touch. Where beacon is affected, name the file and requirement ID the fix belongs in and offer it as separate work.
5. Record the review
Only after the user agrees with the read:
python3 dev/iterm-release.py --ackThat rewrites dev/iterm-reviewed.json; commit it through /anchor:commit.
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.

