ddg-add-pixel
Skill275 starsChanged 4 days agoApache-2.0View on GitHub
Use when adding, renaming or changing a pixel or wide event on iOS, macOS or in SharedPackages, including its JSON5 definition and tests.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .maestro/AGENTS.mdAGENTS.md
- ddg-add-feature-flagSkill
- ddg-apple-feedback-reviewSkill
- ddg-design-systemSkill
- ddg-diagnose-ci-failureSkill
- ddg-drk-add-iconSkill
- ddg-macos-add-promoSkill
- ddg-sentry-reportSkill
- ddg-xcode-add-fileSkill
- verify-iosSkill
The file
Files
Add or change a pixel
These steps cover the usual case. For anything they don't, the Swift API reference is
SharedPackages/PixelKit/Sources/PixelKit/README.md, and the definition rules are in
REVIEW-pixels.md, which Claude Code Review also applies to the PR.
- Find what exists.
git grepthe feature name iniOS/PixelDefinitions,macOS/PixelDefinitionsand*Pixel*.swift. Extend the feature's existingPixelKit.Eventenum when there is one; otherwise create one in its own file.iOS/Core/PixelEvent.swiftis closed to new cases, and Danger fails a PR that adds one. - Name it
feature_actionorfeature-subfeature_action: descriptive, without anm_orm-prefix, and without legacy shorthand likeml.- iOS: leave
iosout of the name. PixelKit appends_ios_phone/_ios_tablet. - macOS: end the name with
_macosand declarevar namePrefix: PixelKitNamePrefix { .none }, otherwise PixelKit prependsm_mac_. SeemacOS/DuckDuckGo/Statistics/FireButtonPixel.swift.
- iOS: leave
- Pick the frequency:
.standardsends every time;.dailyonce per day per device..dailyAndCountsends both, for anything that can spike, such as an error..uniqueByNamesends once per install, and the name must end_u.- The
legacy…cases exist only for pixels that already ship with their suffixes. The README's frequency table lists the rest.
- Fire through an injected
PixelFiring?that defaults toPixelKit.shared. Spell the concrete type,fire(MyPixel.someCase); the leading-dot form.someCasedoes not compile. Bucket numbers, and keep PII and URLs out of names and parameters.- Three or more pixels for one flow, or a wide event: put them behind a
<Feature>Instrumentationprotocol with a default implementation, likeiOS/DuckDuckGo/AIChat/WideEvent/DuckAISessionInstrumentation.swift. .withRetryor.withATB: stop and ask the user for privacy triage first.
- Three or more pixels for one flow, or a wide event: put them behind a
- Define it in
{iOS,macOS}/PixelDefinitions/pixels/definitions/, starting from theTEMPLATE.json5in that folder.- Set
triggersfrom the event that fires the pixel, using the procedure in the "Triggers" section ofREVIEW-pixels.md. Don't default to["other"]. - List every parameter the pixel sends:
appVersionunless the call opts out,errorCodeanderrorDomain(plus the underlying pair) when the event carries an error, andpixelSourcewhen the event declares it. - List suffixes in the order PixelKit emits them: frequency, then
platform, thenform_factor(the last two on iOS only). - A pixel fired from SharedPackages needs a definition on every platform that fires it.
- Set
- Wide events also follow the "Wide events" section of
REVIEW-pixels.md: both definition files, matching version bumps, anchoredkeyPatterns, and no edits togenerated_schemas/. - Test with
PixelKitMock(@_spi(Testing) import PixelKit), asserting on itsactualFireCalls. - Validate from
iOS/ormacOS/:npm ci --include-workspace-rootonce, thennpm run validate-pixel-defs,npm run check-wide-events, andnpm run pixel-lint.fixto format. CI also checksownersagainst an internal GitHub user map that local runs skip, so use GitHub usernames.
Done when every name the Swift code can send has a definition whose parameters and suffixes match, and the validators pass.
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.

