send-it
GitHub全栈发布编排技能，将未提交工作打包为原子提交，运行 lint 预检，生成 Changelog，创建符合 Conventional Commits 规范的 PR，推送代码并同步 Linear 状态。作为核心协调者，委托子技能处理具体步骤，支持单体及多包仓库。
触发场景
安装
npx skills add NeverSight/learn-skills.dev --skill send-it -g -y
SKILL.md
Frontmatter
{
"name": "send-it",
"license": "MIT",
"metadata": {
"author": "Rob Easthope",
"version": "0.6.2"
},
"description": "The all-in-one ship finisher — bundle uncommitted work into atomic commits, run the change-gated lint preflight, author or update the dated changelog entry, compose a Conventional Commits PR title (the release-please bump signal), push, open or update a PR, and transition linked Linear issues to In Review. Use when asked to ship, send it, finish a branch, open or update a PR for the current work, or wrap up and push. A thin orchestrator that delegates the commit step to the `commit` skill, the lint gate to the `preflight` skill, the changelog to the `changelog` skill, and the Linear writeback to the `linear-sync` skill; it owns the branch guard, the release-type decision (by the change's semantic category), PR-title composition, push, and PR. One skill serves monorepos and single-package repos alike.",
"allowed-tools": "Write, Read, Edit, Glob, Grep, Bash(git:*), Bash(gh:*), Bash(pnpm:*), Bash(node:*), mcp__linear-server__get_issue, mcp__linear-server__save_issue, mcp__linear-server__list_issue_statuses",
"compatibility": "Requires the `git` and `gh` CLIs (`gh` authenticated). Node.js ≥22 for the bundled `derive-bump.mjs` \/ `check-skill-bumps.mjs` helpers (Node built-ins only — no npm dependencies, no build step, no tsx). Delegates to the `commit`, `preflight`, `changelog`, and `linear-sync` skills — install them alongside this one. The In Review writeback needs the Linear MCP server (via `linear-sync`); it is skipped if unavailable."
}
send-it
Bundle uncommitted work into atomic commits (via the
commit skill), run the change-gated lint
preflight, author or update the dated
changelog/<ts>-<slug>.md entry (via the changelog
skill), compose a Conventional Commits PR title (the squash subject
release-please reads to decide the version bump), push the branch, open or update
a pull request against the base branch, and transition any linked Linear issues to
In Review (via the linear-sync skill).
This skill is the single source of truth for the ship flow. It is a thin orchestrator: it owns only the glue no sibling skill does — the branch guard, worktree resolution, the release-type decision (by category), PR-title composition, push, and the PR — and delegates the rest:
- Commit → the
commitskill (classify in-scope vs out-of-scope, atomic Conventional Commits, out-of-scope guard). - Lint gate → the
preflightskill (change-gated; no-ops when nothing lint-relevant changed). - Changelog → the
changelogskill (author/update + validate; an entry for every PR, skipped entirely only whenconfig.jsonsetschangelog: false). - Linear In Review → the
linear-syncskill (resolve state by team name, idempotent transition).
The delegated skills auto-detect their own scope, so monorepo features
(per-workspace ESLint fan-out, changelog affected_packages) no-op cleanly in a
single-package repo. send-it configures nothing about them.
Install the delegated skills alongside
send-it. This bundle invokes and links its siblings by relative path (../commit/SKILL.md,../preflight/SKILL.md,../changelog/SKILL.md,../linear-sync/SKILL.md), so a--skill send-it-only install leaves the commit, lint, changelog, and Linear steps unavailable and those links dangling. Install them together:npx skills add https://github.com/acme-skunkworks/agent-skills \ --skill send-it --skill commit --skill preflight --skill changelog --skill linear-sync \ --agent claude-code --agent cursor --copy
This flow intentionally does not run typecheck, tests, or format checks — CI
handles those. The only gate it runs is the change-gated preflight lint.
Configuration
A few knobs live in config.json beside this file; edit your
copied config.json to match the consuming repo (a neutral
config.example.json ships as a template):
| Key | Meaning | Default |
|---|---|---|
baseBranch |
The trunk the branch diff is taken against (origin/<baseBranch>) and the PR base. |
"main" |
shippablePaths (advisory) |
Path prefixes that make up the published surface — a documentation hint for reviewers, not the release decision (A-598; see Step 6). Release-type is decided by the change's semantic category, so these no longer gate the title. Kept for the optional publish-surface cross-check note. | ["skills/"] |
shippableManifestKeys (advisory) |
package.json keys that form the published-files surface — same advisory role as shippablePaths, no longer a release gate. |
["name", "version", "files", "publishConfig"] |
changelog (optional) |
Whether to author a dated changelog/ entry at all (Steps 7–8). Set false for repos with no changelog flow — no changelog/ directory and no changelog skill installed (e.g. a private repo with no release pipeline). When false, send-it skips changelog authoring entirely, and the category decision continues to drive only the PR title. Omit it (or set true) whenever the changelog skill is installed. |
true |
bundleVersioning (optional) |
Enables the per-bundle version-bump check (Step 6) for repos that ship many independently-versioned skill bundles. An object { root, manifest, skillFile } naming the bundle parent dir and the manifest / skill-manifest filenames each bundle carries. Omit it entirely in single-package repos — the check then no-ops. |
unset (disabled) |
The team name, issue-ID prefixes, and workspace slug are not configured here —
they live in the linear-sync and changelog skills' own config.json files,
read by the delegated steps.
Changelog scope (was
changelogScope). send-it authors a dated entry for every PR — the "record everything, filter later" model. Release notes come from filtering the changelog to the version-stamped (release-triggering) entries at release time, not from gating authoring at write time. ThechangelogScopeknob (added in 0.4.0) is gone (A-600); only thechangelog: true|falsemaster switch remains.
Prerequisites
ghCLI installed and authenticated (gh auth status).- The sibling skills (
commit,preflight,changelog,linear-sync) installed.
Process
Step 0: Worktree resolution (only if --worktree= is set)
If --worktree=<branch-or-path> was passed, resolve and cd into that worktree
before any other step runs. Skip this step otherwise.
-
Run
git worktree list --porcelainto list worktrees with their paths and branches. -
Resolve the argument:
- Absolute path (starts with
/): match against theworktree <path>field. - Otherwise: treat as a branch name and match against the
branch refs/heads/<name>field.
- Absolute path (starts with
-
No match — exit immediately with:
No worktree found for <arg>. Available: <comma-separated paths>. -
Match —
cdinto the resolved worktree path. Thecwdpersists for the rest of the workflow, so all subsequentgitandghcalls operate on the worktree. -
Ensure dependencies are present. A freshly-created worktree has no
node_modules. If it is absent, runpnpm install --frozen-lockfilenow — before any step that invokes a bundled script or a validator — so--worktreeis self-sufficient:[ -d node_modules ] || pnpm install --frozen-lockfile -
Continue to Step 1.
This step does nothing when --worktree is omitted — no-arg send-it keeps working
unchanged from whatever directory the session is in.
Step 1: Branch guard
- Get the current branch:
git branch --show-current. - If on the base branch (
baseBranchfromconfig.json; defaultmain):- Run
git status --porcelain. If clean, exit with: "Nothing to ship from the base branch. Create a feature branch first." - If there are uncommitted changes:
- Inspect the diff (
git diffandgit diff --cached) and the changed file paths. - Derive a short kebab-case slug summarising the change (~3 words, lowercase,
max ~40 chars). Examples:
add-readme-section,fix-config-typo. - Branch name resolution (in order):
--branch=<name>— use as-is.--issue=<ID>— use<ID>-<slug>lower-cased (e.g.a-7-as-acquired), matching Linear'sgitBranchName.- Otherwise — just
<slug>(nowip/prefix).
- If the chosen branch already exists locally or on
origin, append-2,-3, … until unused. - Run
git checkout -b <branch>to move the working tree onto it. - Inform the user: "Was on the base branch with uncommitted changes; created
<branch>and continuing."
- Inspect the diff (
- Continue with the rest of the workflow on the new branch.
- Run
- If on a feature branch: continue.
Step 2: Refresh lockfile if package.json drifted
Skip this step if no package.json was touched on the branch.
-
git diff --name-only origin/<base>...HEAD | grep -E '(^|/)package\.json$'. If empty, skip. -
Run
pnpm install --frozen-lockfile. If it succeeds, the lockfile is already in sync — continue. -
If it fails, run
pnpm installto update the lockfile. -
If the lockfile changed, stage and commit it before any other commits go in:
git add pnpm-lock.yaml git commit -m "chore: update lockfile"
This keeps CI's --frozen-lockfile install green. (Skip silently in repos that
don't use pnpm.)
Step 3: Commit uncommitted changes — delegate to the commit skill
send-it is the all-in-one finisher: whatever's uncommitted should be committed before the changelog/PR work begins — but only what belongs to this branch.
Follow the commit skill to do this: classify uncommitted
files in-scope vs out-of-scope against the merge base (git merge-base HEAD origin/<base>), show a staging plan flagging any out-of-scope files (never git add -A; stray files from another branch/worktree are never staged silently), and
create logical atomic Conventional Commits (type + optional scope +
British-English body; ! / BREAKING CHANGE: for breaking changes). If clean,
skip this step. Direct the commit skill to classify against this send-it
run's resolved base — <base> is baseBranch (from config.json), or --base
when passed — not the commit skill's own config.json baseBranch, which
differs on a --base run (the stacked-PR case). The scope classification and the
out-of-scope guard must be computed against the same base send-it ships against,
or a stacked PR would mis-classify files.
The Conventional-Commit types this step writes are the input to Step 6's release
decision (derive-bump.mjs reads them back out of the commits), so the honest
types and ! / BREAKING CHANGE: markers matter.
This delegation covers only the initial commit of uncommitted work. send-it's own later, targeted commits stay here: the lockfile refresh (Step 2), the optional bundle-version bump (Step 6), and the changelog entry (Step 8).
Step 4: Fetch the base branch and confirm there's something to ship
git fetch origin <base>
If git log origin/<base>..HEAD is empty, exit with: "No commits ahead of the base
branch. Nothing to ship."
Step 5: Lint gate — delegate to the preflight skill
--skip-preflightbypasses this whole step. Print a clear⚠️ lint gate bypassed (--skip-preflight)warning and jump to Step 6. Use it only when the gate misfires; CI still runs the repo's real linting.
Run the change-gated lint preflight, following the preflight
skill:
node skills/preflight/scripts/preflight.mjs
Act on its exit-code contract, reading .preflight-summary.json to interpret a
non-zero exit:
- Exit 0 — pass. No introduced violations; continue.
- Exit 1 with
violations.introducedCount > 0— introduced violations (blocking). Runnode skills/preflight/scripts/lint-fix.mjs, re-run preflight, and repeat until introduced violations clear. Commit the fixes (astyle:/fix:commit, or fold into the relevant Step 3 commit if not yet pushed) before continuing. - Exit 1 with
introducedCount == 0andresults.failedLintersnon-empty — a linter could not run (its binary is absent), not a real violation. This is expected in a repo that doesn't use that toolchain (e.g. a docs/skills repo with no ESLint or markdownlint installed). Treat it as a skip, not a block: warn that<linter>was unavailable and continue. The repo's own CI owns whatever linting it actually runs. - Exit 2 — pre-existing violations only. Not introduced by this branch — do not block shipping. Surface them and continue (optionally offer a debt issue per the preflight skill).
Preflight is change-gated: it lints only the categories the branch touched, so
it no-ops when nothing lint-relevant changed. Skip this step entirely only if
preflight isn't installed.
Step 6: Decide release-type by category and compose the Conventional Commits PR title
Versioning is driven by release-please
reading Conventional Commits. The repo squash-merges, so the squash subject is
the PR title — and that single conventional title is what release-please parses to
decide the bump. send-it composes a correct conventional title and writes the dated
changelog entry (for every PR — see Step 7). It does not bump versions, write any
CHANGELOG.md, or tag.
Release-type is decided by the change's semantic category — the Conventional-Commit
type of the work send-it itself committed — not by which paths the diff touches
(A-598). A docs-only edit is docs: (no release) even when it lives under a published
path like skills/; a feat: is a release wherever its files sit. (Earlier versions
keyed this off shippablePaths, which mis-titled a docs edit inside a published path
as feat:/fix: and cut a spurious release.)
-
Derive the slug, body, type, and category from the branch commits via the bundled helper (zero-dep — no tsx):
node skills/send-it/scripts/derive-bump.mjsIt prints JSON:
{ "slug", "bump", "body", "type", "breaking", "category", "releaseTriggering" }:type— the Conventional-Commit type of the lead commit (feat/fix/perf/docs/refactor/chore/ci/…); this is the PR-title prefix.breaking—trueif any commit carries a!or aBREAKING CHANGE:trailer.category— the dated changelogcategoryenum value (feat→feature,fix→fix,perf→perf,docs→docs,refactor→refactor, everything else →chore).releaseTriggering—trueiffbreakingortype ∈ {feat, fix, perf}. This is the release decision:truecuts a release,falsedoes not.bump—major/minor/patch, the release magnitude whenreleaseTriggering(aBREAKING CHANGE:/!→ major; leadfeat:→ minor; else patch). Ignored whenreleaseTriggeringisfalse.
-
(Advisory) publish-surface cross-check.
shippablePaths/shippableManifestKeysinconfig.jsonare a documentation hint of the published surface — they do not decide release-type any more. Optionally sanity-check the category against them: ifreleaseTriggeringistruebut the diff (git diff --name-only origin/<base>...HEAD) touches noshippablePathsprefix (nor ashippableManifestKeyskey inpackage.json), note it in the PR body so a reviewer can confirm the release was intended — and likewise if a change touching a published path isreleaseTriggering: false. This is a soft note only; never let it override the category decision or block. -
Check per-bundle version bumps — only when
config.jsonsetsbundleVersioning(multi-artefact repos; skip this step entirely when it's unset). Each skill bundle carries its own version in itspackage.json+SKILL.md metadata.version, bumped by hand and decoupled from the repo release. CI enforces that the two agree, but nothing enforces they were bumped when the bundle's content changed — so an edited bundle can ship with a stale version label. Close that gap:node skills/send-it/scripts/check-skill-bumps.mjsIt prints
{ "configured", "unbumped": [{ name, currentVersion, suggestedBump, suggestedVersion, manifestPath, skillPath }], "bumped" }. For eachunbumpedentry, surface the proposal and apply it on confirmation:skills/<name>changed but its version is still<currentVersion>. Suggested bump:<suggestedBump>→<suggestedVersion>(matches the PR-title bump). Apply? (yes / no / patch / minor / major)On
yes(or an explicit level), edit bothmanifestPath(version) andskillPath(metadata.version) to the chosen version — in lockstep, so the parity invariant CI checks still holds — then stage and commit just those two files:git commit -m "chore(<name>): release <name>@<version>". Onno, leave it and continue. Under--dry-run, print the proposal and edit nothing. -
Compose the PR title as a single Conventional Commits subject — this is the release-please bump signal and is enforced by CI's PR-title lint. If
--titlewas passed, use it verbatim (still runderive-bumpabove for the changelogcategory, and warn — don't block — if the supplied type contradicts the derivedtype/releaseTriggering). Otherwise build it straight from the derived fields:- Prefix =
type(add a scope when one is obvious, e.g.feat(<scope>):), plus!whenbreaking— sofeat: <body>,fix: <body>,perf: <body>,docs: <body>,refactor: <body>,chore: <body>,feat!: <body>, etc. - Release-triggering (
releaseTriggering: true) → the prefix is already a release type (feat/fix/perf, or any!); release-please cuts the bump from it. Add the scope; that's it. - Non-release (
releaseTriggering: false) → the prefix is a non-release type (docs/refactor/chore/ci/build/test/style); release-please cuts nothing.
⚠️ The PR title is the version. A mistyped prefix silently ships the wrong semver — a
feat:on a docs PR cuts a needless release; achore:on a real fix ships nothing. There is no changeset file to cross-check against: the title is the declaration. It comes straight from the change's semantic category (the commit types) — keep the commit types honest and the title follows.When
releaseTriggeringisfalse, noteno release (<type>-only)in the PR body so reviewers can confirm the non-release type was intentional. - Prefix =
Step 7: Author or update the dated changelog entry — delegate to the changelog skill
Disabled entirely? If
config.jsonsetschangelog: false, skip Steps 7 and 8 completely — author nothing, run nochangelogscripts, make nodocs(changelog)commit — and note "changelog step disabled (no changelog flow in this repo)" in the run summary. This is for repos with nochangelog/directory and nochangelogskill installed; the category decision from Step 6 still drives the PR title. Whenchangelogis unset ortrue, always author an entry (thechangelogScopeknob was removed — A-600).An entry for every PR. send-it authors a dated
changelog/entry for every PR, release-triggering or not — the "record everything, filter later" model. The dated changelog is the full record of merged work; release notes filter it to the version-stamped (release-triggering) entries at release time, so a non-release entry simply carries noversion.changelog: falseis the only thing that suppresses authoring.
Follow the changelog skill to author or update the entry:
-
Detect an existing entry for this branch (by the
branchfrontmatter field) → update vs create. On update, preserve the filename andcreated_at. -
Write/refresh
changelog/<YYYYMMDD-HHMMSS>-<slug>.md(the<slug>from Step 6), derivingtitle/release_note/issuesfrom the branch. Setcategoryandbreakingstraight fromderive-bump's output (Step 6):categoryis itscategoryfield (feature/fix/perf/docs/refactor/chore— the changelog enum), andbreakingis itsbreakingflag. For a non-release entry (releaseTriggering: false),release_notemay be blank when there's no user-facing impact.Leave the post-merge fields (
merged_at,commit,pr,stats) andversionas blank placeholders — the post-merge enricher fills them (a non-release entry keepsversionblank, as no release is cut for it). This includespr: no step here writes it back after the PR opens; the post-merge enricher resolves it from the entry'sbranch:. -
Run the enrichment scripts:
node skills/changelog/scripts/set-affected-packages.mjsthennode skills/changelog/scripts/add-links.mjs. -
Validate:
node skills/changelog/scripts/validate-changelog.mjs. It must pass before committing — if it fails, surface the error and abort; don't auto-fix.
Step 8: Commit the changelog entry and push
If a changelog/ entry was written in Step 7 (i.e. changelog is not false), commit
only that file:
git add changelog/<YYYYMMDD-HHMMSS>-<slug>.md
git commit -m "docs(changelog): <one-line summary>"
Then push the branch:
git push -u origin <branch>
Step 9: Create or update the PR
<title> is the Conventional Commits PR title from Step 6 — release-please reads it
as the squash subject, so set it on both create and update (re-derive it every
run so it stays in sync with the branch's commits).
- Check for an existing PR:
gh pr view --json number,url 2>/dev/null. - If creating:
gh pr create --base <base> --draft --title "<title>" --body "<body>". Use--ready(the flag) instead of--draftif the user passed--ready. - If updating:
gh pr edit <number> --title "<title>" --body "<body>". - If
--merge-when-readywas passed: after create/update, rungh pr merge --auto --squash <number>to enable auto-merge once requirements are met. - Return the PR URL via
gh pr view --json url -q '.url'.
PR body template:
## Summary
- Comprehensive summary of all changes on this branch
- What changed and why
## Related Issues
<!-- Linear identifiers extracted from the branch and commits -->
- <ISSUE-ID>
## Test Plan
- [ ] <test>
Drop the ## Related Issues section if no issues were found.
Step 10: Transition linked Linear issues to In Review — delegate to the linear-sync skill
Follow the linear-sync skill with target state In
Review: read its config.json for linearTeamName and issueKeys, extract issue
IDs from the branch and commits, resolve the live state ID by team name (once),
and apply the transition idempotently (skip any issue already at or past In Review).
Skip silently if linear-sync or the Linear MCP server is unavailable.
Flags
--dry-run— print what would be written/submitted (changelog preview, branch, conventional PR title, any version-bump proposals), make no commits, no push, noghcalls. Exit 0.--branch=<name>— override the auto-derived branch name when running on the base branch with uncommitted changes.--issue=<ID>— prefix the auto-derived slug with a Linear issue ID (e.g.--issue=A-7→a-7-<slug>, lower-cased). Ignored if--branchis given.--base=<branch>— overrideconfig.json'sbaseBranchfor this run. Applies everywhere the base is used: thegit fetch, the branch diff (origin/<base>...HEAD), the PR--base, and theBASE_REF=origin/<branch>env passed toderive-bump.mjs/check-skill-bumps.mjs. Use it for stacked PRs or a non-maintarget.--title="<conventional subject>"— set the PR title verbatim instead of deriving it (escape hatch for when derivation picks the wrong type). It must still be a valid Conventional Commits subject (CI lints it).derive-bumpstill runs (itscategorydrives the changelog entry); send-it warns if the supplied type contradicts the derivedtype/releaseTriggering.--skip-preflight— skip the Step 5 lint gate entirely, printing a bypass warning.--ready— open the PR ready-for-review instead of draft (default is draft).--merge-when-ready— after create/update, enablegh pr merge --auto --squash.--worktree=<branch-or-path>—cdinto a worktree before running (Step 0).
Notes
- Prose follows the host repo's language convention. Author the PR title, PR
body, and commit messages in the consuming repo's documented prose language. Across
this estate that is British English (
colour,behaviour,-ise/-yse); thechangelogskill applies the same rule to the entry it writes. This governs prose only — never identifiers, dependency names, or upstream API field names. - Trunk-based: PRs target the base branch (
config.jsonbaseBranch, or--basefor this run). - send-it bumps only per-bundle versions, never the repo version. The optional
Step 6 bundle-version check moves a changed skill's own
metadata.version; the repo-level npm release stays owned by release-please via the PR title. - Idempotent: re-running send-it updates the existing PR title and changelog entry; the Linear writeback skips issues already In Review or beyond.
- send-it does not bump versions or write any
CHANGELOG.md. release-please reads the merged Conventional-Commit PR title, bumps the manifest in the release PR, and the release workflow publishes + tags. send-it only writes the datedchangelog/<ts>-<slug>.mdentry (Step 7), finalised post-merge by the in-repo enricher.
Error Handling
gh auth statusfails — rungh auth loginfirst; abort until authenticated.- changelog validation fails — surface the error; don't auto-fix. The user resolves the entry and re-runs.
- No commits ahead of the base — exit "No commits ahead of the base branch. Nothing to ship."
- Branch push fails — verify push access; ensure the remote is configured.
- PR create/update fails — verify the PR isn't closed; verify the branch is pushed.
版本历史
- c3c0a1e 当前 2026-07-23 10:21
依赖关系
-
suggested
https://github.com/acme-skunkworks/agent-skills
