PyModel/pythinker-code / .agents/skills/gen-changesets
gen-changesets
VerifiedUse when generating changesets in the pythinker-code repository — deciding whether to write one, which package to list, the bump level, the wording, and the confirmation workflow.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.2 KB |
SKILL.md
View on GitHub---
name: gen-changesets
description: Use when generating changesets in the pythinker-code repository — deciding whether to write one, which package to list, the bump level, the wording, and the confirmation workflow.
---
# Generate Changesets
The only user-facing published package is the CLI: `@pymodel/pythinker-code`. All other `@pymodel/*` packages (sdk, agent-core, kosong, oauth, telemetry, and so on) are internal.
## 1. Whether to Write
Rule of thumb: **if users cannot perceive the change, write no changeset.** A changeset is a user-facing changelog entry, not a shipping gate — internal changes merged to main ship with the next release anyway, so skipping loses nothing.
Do not write:
- Docs-only or tests-only changes that never enter the shipped artifact.
- Changes internal to core/server packages — architecture, protocols, refactors, config/journal/wire mechanics — unless they fix a bug users care about.
- When you are unsure whether users can perceive a change, ask first.
Do write: user-perceivable new features or behavior changes, and internal-package changes that fix a user-useful bug or change CLI output/behavior (list `@pymodel/pythinker-code` for those).
## 2. What to Write
Create a short kebab-case file under `.changeset/`:
```markdown
---
"@pymodel/pythinker-code": patch
---
Fix occasional loss of tool call results in long conversations.
```
Wording:
- One short, user-facing English sentence that states only what changed. Drop trailing clauses that explain the cause, the benefit, or the mechanism.
- When a default flips or an existing behavior is removed, name the behavior users lose, not only the new default. State the escape hatch if one exists, e.g. `Stop hot-reloading config, skills, and AGENTS.md by default; set [watch] enabled = true or PYTHINKER_CODE_WATCH=1 to turn it back on.`; if there is none, say plainly that the old behavior is no longer available.
- New features: say plainly what it is plus one line on how to use it, e.g. `Add the /foo slash command to list active sessions. Run /foo to see them.`
- Experimental features: also state how to enable them (the flag, config key, or env var).
- No file, class, or function names, and no PR numbers. No vague words like refactor, optimize, or improve. No real internal identifiers — use neutral placeholders such as `example.com` or `YOUR_API_KEY`.
- Internal packages' own changelogs (such as the sdk) are not curated for end users — write those entries honestly and technically.
- One logical change per changeset; split unrelated changes into separate files.
## 3. Bump Level
- `patch`: bug fixes, small improvements, configuration additions to existing features — when in doubt, use this.
- `minor`: a real new capability users could not do before (a new slash command, a new subcommand, a new mode).
- `major`: **never write it.** If you think a change qualifies, stop and ask the user; without explicit approval fall back to `minor`, or to `patch` if `minor` is also unclear.
## 4. Which Package
- An internal change enters the CLI bundle and is user-perceivable → list `@pymodel/pythinker-code`.
- An internal change does not enter the CLI or is not user-perceivable → write nothing; if it is written, list only that internal package.
- Never mix packages ignored in `.changeset/config.json` with non-ignored packages in one frontmatter.
- pi-tui exception: pi-tui-only changes list `@pymodel/pi-tui`; if the same change is also visible to CLI users, write a separate CLI changeset (two files, never mixed).
- pythinker-inspect and the vis packages never appear in a changeset.
## 5. Workflow
1. Run `git status` / `git diff --name-only` to see which packages actually changed.
2. Apply section 1; if no changeset is needed, stop.
3. Pick the package and the bump, and write the one sentence.
4. **Show the changeset text to whoever requested the work and get their confirmation before committing.**
5. Do not guess at changes you do not understand: finish the parts that are clear, then list what is unclear and ask whether you may dig into the code.
Before a release, review the accumulated `.changeset/` entries and delete the non-user-facing ones — the release PR regenerates from `.changeset/` on main, so deleting a file removes its changelog entry without touching shipped code.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |