add-event-type
Skill874 starsChanged 6 days agoMITView on GitHub
Add a new persisted event (custom event_type in the append-only log) or a transient UI event, with its producer, readers and tests. Use when the core, harness or a run needs to record or announce something new.
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- src/AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- src/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- add-event-typeSkill
- add-ipc-channelSkill
- add-plugin-toolSkill
- better-colorsSkill
- better-layoutSkill
- better-typographySkill
- better-uiSkill
- better-writingSkill
- breakSkill
- harness-incident-fixSkill
- run-area-testsSkill
- variantSkill
- verify-ui-via-dev-controlSkill
- wire-artSkill
- add-ipc-channelSkill
- add-plugin-toolSkill
- better-colorsSkill
- better-layoutSkill
- better-typographySkill
- better-uiSkill
- better-writingSkill
- breakSkill
- harness-incident-fixSkill
- run-area-testsSkill
- variantSkill
- verify-ui-via-dev-controlSkill
- wire-artSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
If a later session, the chat transcript, Studio activity or a run review must show it, it is persisted.
- Very specific: line 20
Keep EventData in src/shared/event-log.ts unchanged.
- Very specific: line 37
Read it where it shows up: src/shared/studio-activity.ts (STUDIO_RECORD_EVENTS), src/shared/chat-activity.ts, src/shared/run-review.ts, …
- Distinctive: line 44
Never rewrite or delete old events to migrate.
≈ “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
Add an event type
Two kinds exist. Pick one before writing code.
| Kind | Survives restart | Producer | Transport |
| Persisted | yes; the log is the agent's whole state | core append, harness events.append | studio:events pull |
| Transient UI | no | core emit, harness ctx.notify / ui.notify | studio:event push |
If a later session, the chat transcript, Studio activity or a run review must show it, it is persisted. Progress ticks, status lines and "refresh now" hints are transient.
Persisted: a custom event
- Keep
EventDatainsrc/shared/event-log.tsunchanged. New events are{ type: "custom", event_type: "snake_case_name", payload }. Add a new top-leveltypeonly for a new substrate primitive (and updatenormalizeEventinsrc/substrate/event-store.ts). - Contract first, in
src/shared/custom-events.ts: add a PascalCase key with its exact wire value toCustomEvent(CUSTOM_EVENT_TYPESis derived), and, when the app reads it, its payload toCustomEventMap(a map key the registry lacks fails the typecheck). Every field is optional: old logs and self-edited harness code can emit partial payloads. Reuse a payload type that already lives insrc/shared(AssetDeliveredPayload,PluginToolStartedPayload, …). - Produce it (
NewEventbelow stands for the key you add; use the seedHostMethodfromsrc/harness-seed/loop/host-methods.tsfor harness calls):- core:
await this.append([customEventData(CustomEvent.NewEvent, payload)], threadId)insrc/main/studio-core.ts(or the module that owns the behaviour); - harness:
await ctx.call(HostMethod.EventsAppend, {batch:[...]})(typed byHarnessHostApiinsrc/shared/harness-api.ts), as insrc/harness-seed/tools/self-tools.ts. Harness-seed is shipped product payload: edit it as product code, and add an incident row (theharness-incident-fixskill).
- core:
- Read it where it shows up:
src/shared/studio-activity.ts(STUDIO_RECORD_EVENTS),src/shared/chat-activity.ts,src/shared/run-review.ts,src/renderer/chat-entries.ts,src/renderer/run-graph.ts,src/renderer/build-progress.ts. Read the payload withcustomEvent(event, CustomEvent.NewEvent)/customPayload(data, [CustomEvent.NewEvent])(nullfor any other event,{}for a missing payload),delegatedPayloadfordelegated.<engine>, orcustomRecordfor any custom event; nodata.payload as. Grepevent_type ===to find every consumer of a similar event, and keep the names consistent with them. - Never rewrite or delete old events to migrate; readers accept both shapes.
Transient: a UI event
- Contract first: add the exact wire name and payload to
UiEventMap, and a PascalCase key toUiEventinsrc/shared/ui-events.ts;UI_EVENT_TYPESis derived (named likerun.finishedorpreview.frame). Fields the harness writes stay optional: it is edited at runtime and main forwards its notifications unchanged. - Core:
this.emit(UiEvent.NewEvent, payload), typed by the map; main'spushUiEventinsrc/main/index.ts(also typed) forwards it asstudio:event(a push channel ofsrc/shared/ipc-channels.ts). - Harness: keep the matching wire name in a seed-owned
as constvocabulary beside its producer, then callctx.notify(SeedUiEvent.NewEvent, payload). The example name stands for that vocabulary; there is no shared seedUiEventexport. Never import app source into the editable seed. Keep the seed/app contract covered by its contract tests. - Renderer:
window.studio.onEvent(event => { if (event.type === UiEvent.NewEvent) … })narrows the payload;isUiEventIn(event, "area.")narrows a family. Noevent.payload as. tests/conformance/ui-events.test.tsfails when a produced name is missing from the map, or a key is no longer produced.- Nothing may depend on a transient event having been seen; the next pull must be able to rebuild the state.
Tests (red first)
tests/conformance/custom-events.test.tsscanssrcas data and fails when the code writes or reads a custom event name missing fromCUSTOM_EVENT_TYPES, or the registry keeps a name nothing uses.- Reader: feed synthetic
EventEnvelopes (including an old/partial payload) to the pure reader, astests/conformance/studio-activity.test.tsandchat-history.test.tsdo. - Producer: drive the behaviour through
tests/helpers/core-lite.tsand read the log back withcore.store.listEvents(threadId); for harness producers usestartRigandcustomEventsfromtests/helpers/studio-rig.ts. - Log invariants:
tests/conformance/event-store.test.tswhen touching the store itself.
npm test -- tests/conformance/studio-activity.test.ts tests/conformance/<producer>.test.tsDoes 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.

