# Pull Lexicons

> Use when asked to pull, sync, update, or refresh the latest AT Protocol lexicons for the definitions packages — runs pull + generate, classifies each package's diff, and commits per package.

- Skill: `mary-ext/pull-lexicons` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mary-ext/pull-lexicons`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mary-ext/pull-lexicons/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mary-ext (https://skillmd.com/u/mary-ext)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mary-ext/pull-lexicons

---


# Pulling Lexicons

Refreshes the generated lexicon definitions from upstream services and commits the result, one
commit per package. Invoking this skill authorizes those commits for this run.

## Workflow

Run from the repo root:

```
pnpm run -r pull
pnpm run -r generate
```

`-r` fans out across the workspace; only the `packages/definitions/*` packages define these scripts,
so those are the only ones that change.

Then `git status` and handle **each changed definitions package independently** — classify its diff,
then act:

1. README only — only the `lexicons/README.md` regenerated → discard it (`git restore`). The README
   regenerates on every pull; its churn alone carries no real change.
2. Docs only — lexicon sources (the JSON under `lexicons/`) changed, generated code under `lib/` did
   not → commit, no changeset. Nothing in the published API surface moved, so there's no version to
   bump.
3. Docs and code — both the lexicon sources and the generated code under `lib/` changed → add a
   changeset (unless one already exists — see below), then commit.

Each package gets its own commit. The regenerated `lexicons/README.md` rides along in cases 2 and 3
(only case 1 discards it).

## Commit

Message — short package name in the scope, service name capitalized (proper noun):

```
chore(<pkg>): pull latest <Service> lexicons
```

e.g. `chore(frontpage): pull latest Frontpage lexicons`. Use `chore`: these pulls are upstream
refreshes, not new API surface, so never `feat`.

## Changeset (case 3 only)

Write `.changeset/<pkg>-pull-lexicons.md`, using the package's full `@atcute/<pkg>` name:

```markdown
---
'@atcute/<pkg>': patch
---

pull latest <Service> lexicons
```

Always `patch`. Lexicon refreshes don't follow semver here — even an upstream breaking change is a
patch bump (see [[definitions_versioning]]).

If `.changeset/<pkg>-pull-lexicons.md` already exists from an earlier unreleased pull, leave it and
commit the code alone — the rewrite would be byte-identical, and the existing changeset already
covers this bump. This keys on that exact file: a different pending changeset that happens to bump
`@atcute/<pkg>` doesn't count, so still write yours.

## Stop for highly-breaking changes

One exception forces a stop: a **highly-breaking** change needs a major bump and is yours to call.
The signature case is a service relocating to a new NSID namespace, which changes _how the package's
types are exported_ — e.g. Frontpage moving to `fyi.frontpage.*` (frontpage `2.0.0`). A field tweak
or added definition is not this.

When you spot one, **stop and defer to the user** rather than committing — surface the change and
ask how to version it.