// Use when preparing a Freshell release — before bumping versions, writing release notes, tagging, etc on GitHub.
| name | release-freshell |
| description | Use when preparing a Freshell release — before bumping versions, writing release notes, tagging, etc on GitHub. |
Invoke this skill before changing version numbers or cutting a release. Never release without explicit user request.
Before anything: if something seems off (discontinuous version jump like 0.25→2.6, failing tests, broken code), stop and confirm with the user.
Release notes are user-facing, not code-facing. Write from the perspective of someone using Freshell, not someone reading the git log.
Two sections, in this order:
"New things you can do" — Features that let users do something they couldn't before. Each item: what it is + why you'd care. Priority-ordered (most impactful first).
"Things that got better" — Improvements to existing functionality. Same format: what changed + why it matters. Priority-ordered.
# 1. Get the full commit list
git log v<PREV>..HEAD --oneline --no-merges
# 2. Get the diffstat for scope
git diff v<PREV>..HEAD --stat | tail -5
# 3. For commits that touch user-facing code, read the diffs
git show <hash> --stat # what files changed?
git show <hash> # read the diff if unclear from commit message
# 4. Walk through commits and ask: "What can the user now DO differently?"
## What's New
### New things you can do
- **Launch a coding agent directly** — Pick Claude Code or Codex from the pane picker,
choose a directory with fuzzy search, and launch. No manual cd + typing commands.
- **Know when an agent is done** — Turn-complete bell and tab attention indicators
notify you when a coding CLI finishes its turn.
### Things that got better
- **Faster session sidebar** — Updates arrive as incremental patches instead of
full re-sends. Noticeably snappier with many sessions.
- **Paste is reliable** — All paste paths go through one pipeline. No more
double-pastes or dropped pastes.
Freshell uses semver. Decide the bump with the user, but offer a recommendation:
This is the last step before mechanical release, and requires user approval.
Review README.md's Features section against the current state of the product. Read the relevant source code to verify claims — don't trust the README or your memory alone.
For each feature listed:
Present the proposed README changes to the user for approval before proceeding to release steps.
All release preparation happens on a release branch in a worktree from origin/main. Local main is a mirror of origin/main; do not commit to it, fast-forward it, or push it directly.
# From the repo root
git fetch origin
git worktree add .worktrees/release-vX.Y.Z -b release/vX.Y.Z origin/main
cd .worktrees/release-vX.Y.Z
npm install
# In the worktree — start from a clean slate to catch peer dep issues
rm -rf node_modules
npm install
# Type-check AND build (catches errors vitest misses because it transpiles with esbuild)
npm run build
# Run the full test suite
npm test
All three commands must succeed. npm install must complete without --force or --legacy-peer-deps. npm run build catches TypeScript errors that npm test alone does not (vitest uses esbuild for transpilation, skipping type checking). If any step fails, fix the issue on the release branch before proceeding.
All of these are committed to the release branch:
package.json--branch vOLD to --branch vNEW in the clone command, and apply the approved Features changesrelease: vX.Y.ZPush the release branch and open a PR against main. After user approval and required checks, merge it through GitHub. If conflicts appear, rebase the release branch onto origin/main, resolve in the worktree, retest, and force-push with --force-with-lease.
git fetch origin
git tag -a vX.Y.Z -m "vX.Y.Z"
git push --tags
gh release create vX.Y.Z --title "vX.Y.Z" --notes "..." # with the release notes
git worktree remove .worktrees/release-vX.Y.Z
git branch -d release/vX.Y.Z
main mirrors origin/main; release work happens on a PR branch.dev, not local main.Use when reviewing, triaging, or landing pull requests — especially batches of open PRs that need inspection, fixes, and merging. Also triages open issues after the PR queue is clear.
Use when interacting with Freshell panes, panels, or tabs from the CLI for tmux-style automation and multi-pane workflows, outside external-browser automation tasks.
Use when installing, creating, or setting up Freshell extensions — from GitHub repos, local directories, or from scratch as custom panes.
Use when producing screen-recorded demos that need scenario-specific pane layouts, live interaction walkthroughs, and machine-readable timecodes for automated video editing.
Use when producing screen-recorded demos that need scenario-specific pane layouts, live interaction walkthroughs, and machine-readable timecodes for automated video editing.