autoship — Skillopedia

Autoship Automate npm releases with a changeset - fix - push - monitor - merge - publish workflow. Reference Files | File | Read when | |------|-----------| | | Creating a changeset, fixing quality issues, or committing and pushing | | | Watching CI with the Monitor tool, diagnosing failures, or handling retries | | | Searching for the Version Packages PR, merging it, or watching the release workflow | Intent Map | Intent | Steps | Notes | |--------|-------|-------| | Full autoship (ship / release / publish) | 1 through 5 | Default entry point. Runs end-to-end through publish without intermed…

; then\n echo \"TERMINAL: failure\"\n else\n echo \"TERMINAL: success\"\n fi\n exit 0\ndone\n```\n\nThe agent keeps the Monitor running; each state change surfaces a new block. Stop on the first `TERMINAL:` line. Any non-`success` conclusion (`failure`, `cancelled`, `timed_out`, `action_required`, `neutral`, `skipped`, `stale`) is reported as a failure so the agent can inspect logs rather than spin.\n\n## Waiting for the Version Packages PR to Appear\n\n`changesets/action` may take several minutes to open the PR after the changeset commit lands on the default branch. Watch for it:\n\n```bash\nDEADLINE=$(( $(date +%s) + 600 )) # 10-minute cap\nwhile [ \"$(date +%s)\" -lt \"$DEADLINE\" ]; do\n PR=$(gh pr list --state open --search \"Version Packages in:title\" \\\n --json number,headRefName \\\n --jq '.[] | select(.headRefName == \"changeset-release/main\") | .number' | head -n1)\n if [ -n \"$PR\" ]; then\n echo \"FOUND: $PR\"\n exit 0\n fi\n sleep 30\ndone\necho \"TIMEOUT\"\nexit 1\n```\n\nStop the Monitor on `FOUND:` or `TIMEOUT`.\n\n## Watching the Publish Workflow\n\nAfter merging the Version Packages PR, the same release workflow runs again (this time invoking `changeset publish`). Identify the workflow file in `.github/workflows/`, then:\n\n```bash\nWF=\"release.yml\" # adjust to the actual file name\nLAST=\"\"\nwhile true; do\n CUR=$(gh run list --workflow \"$WF\" --branch main --limit 1 \\\n --json status,conclusion,databaseId \\\n --jq '.[0] | \"\\(.databaseId)|\\(.status)|\\(.conclusion // \"\")\"')\n if [ \"$CUR\" != \"$LAST\" ]; then echo \"$CUR\"; LAST=\"$CUR\"; fi\n case \"$CUR\" in\n *\"|completed|success\") echo \"TERMINAL: success\"; exit 0 ;;\n *\"|completed|\"*) echo \"TERMINAL: failure\"; exit 0 ;;\n esac\n sleep 30\ndone\n```\n\nPipe (`|`) is used as the field delimiter instead of tab so the case patterns can anchor on the end of the string and avoid the trailing-delimiter trap. Any conclusion other than `success` is treated as a failure so non-standard terminal states (`neutral`, `skipped`, `action_required`, etc.) are surfaced rather than silently looped.\n\nDo not auto-retry on publish failure — these are real (auth, OIDC, tag conflict).\n\n## Failure Diagnosis\n\nWhen a Monitor reports a failed run:\n\n1. Read the failed logs: `gh run view \u003cid> --log-failed`.\n2. Classify the failure:\n\n| Type | Indicators | Action |\n|------|-----------|--------|\n| Flaky test | Intermittent, passes on re-run, known flaky test names | `gh run rerun \u003cid> --failed`, restart the Monitor |\n| Real failure | Consistent, reproducible, related to the changes | Fix code, commit, push, restart the Monitor |\n| Infrastructure | Network timeout, runner issue, service unavailable | `gh run rerun \u003cid>`, restart the Monitor |\n\nRetry flaky/infrastructure failures up to 3 times. After 3 retries, escalate to the user. Never auto-retry the publish workflow.\n\n## Stopping a Monitor\n\nA Monitor stops when its script exits (the examples above exit on `TERMINAL:` / `FOUND:` / `TIMEOUT` lines). To cancel an in-flight Monitor before it exits, ask the agent to stop it. Always stop monitors before reporting autoship complete.\n\n## Rate Limit Awareness\n\n`gh` calls count against your GitHub API rate limit. Keep `sleep` at 30s or higher in Monitor scripts. Check remaining quota if you suspect throttling:\n\n```bash\ngh api rate_limit --jq '.resources.core.remaining'\n```\n\n## The Changeset Status PR Check\n\nChangesets repos typically run `npx changeset status --since origin/\u003cbaseBranch>` on every PR (often as a step in the main CI job). This check verifies that a PR modifying publishable code includes a pending `.changeset/*.md` file.\n\nCommon failure modes:\n\n- **\"no changeset found\"** — the PR touches code but adds no changeset. Fix: run Step 1 of autoship to add one.\n- **\"changeset consumed\"** — a local `npx changeset version` was run; the changeset file is gone and `package.json` version has already been bumped. Fix: revert the version bump + `CHANGELOG.md` edit, re-add the changeset file, force-push. Do NOT retry CI — the state is broken at the commit level.\n\nThis check is what you read first when a release PR fails CI.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6217,"content_sha256":"fa64ebaed6e1048c2ef5990438e30bd2da696422927be5502b4fb48709aaed99"},{"filename":"references/version-pr-and-publish.md","content":"# Version Packages PR and npm Publish\n\n> **Companion reference:** this file points to reusable Monitor snippets in `references/ci-polling.md` (sections \"Waiting for the Version Packages PR to Appear\" and \"Watching the Publish Workflow\"). Load `ci-polling.md` alongside this file whenever you work through autoship Steps 4 or 5.\n\n## Table of Contents\n\n- [The `changesets/action` Workflow](#the-changesetsaction-workflow)\n- [Finding the Version Packages PR](#finding-the-version-packages-pr)\n- [Verifying CI Before Merge](#verifying-ci-before-merge)\n- [Merging the Version Packages PR](#merging-the-version-packages-pr)\n- [Watching the Publish Run](#watching-the-publish-run)\n- [Cleanup](#cleanup)\n\n## The `changesets/action` Workflow\n\nA single workflow (commonly `release.yml` or `npm-publish.yml`) handles both versioning and publishing. It runs on pushes to the default branch and uses `changesets/action@v1` with a `publish:` input pointing at an npm script that calls `changeset publish` (typically `npm run release`).\n\nThe action has two modes, chosen automatically by state on `main`:\n\n1. **Pending changesets present** → it runs `changeset version` internally, then opens or updates a PR titled \"Version Packages\" on branch `changeset-release/main` containing the version bump and `CHANGELOG.md` updates. No publish yet.\n2. **No pending changesets (Version Packages PR just merged)** → it runs the `publish:` script, which calls `changeset publish` to push tags and publish to npm.\n\nSo the SAME workflow run that opens the Version Packages PR does not publish; a second run of the SAME workflow, triggered by merging that PR, publishes. When monitoring, you are watching two successive runs of one workflow — not two different workflows.\n\nReference best-practice `release.yml` shape (OIDC trusted publishing):\n\n```yaml\npermissions:\n contents: write\n pull-requests: write\n id-token: write\nsteps:\n - uses: actions/checkout@v4\n with: { fetch-depth: 0 }\n - uses: actions/setup-node@v4\n with: { node-version: 22, registry-url: https://registry.npmjs.org, cache: npm }\n - run: npm ci\n - uses: changesets/action@v1\n with:\n publish: npm run release\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n NPM_CONFIG_PROVENANCE: \"true\"\n```\n\nThe `release` script is typically `changeset publish` (optionally preceded by a build). The `changeset:version` npm script, if present, is invoked by the action, **never locally**.\n\n`.changeset/config.json` should have `\"commit\": false` so the action controls commits via the PR.\n\n## Finding the Version Packages PR\n\n### With `gh` CLI\n\n```bash\n# Search by title\ngh pr list --search \"Version Packages\" --state open --json number,title,headBranch,statusCheckRollup\n\n# Search by branch pattern\ngh pr list --head changeset-release/main --state open --json number,title,statusCheckRollup\n```\n\n### If the PR Does Not Exist Yet\n\nThe changesets bot may take a few minutes. Use the `Monitor` tool to watch for the PR (see the \"Waiting for the Version Packages PR to Appear\" snippet in `references/ci-polling.md`). Cap the watch at 10 minutes. If the watch times out, check:\n\n- Are there pending changesets on the default branch?\n- Is the changesets GitHub Action configured in `.github/workflows/`?\n- Did the action run? Check with `gh run list --workflow \u003cchangeset-workflow-name>`\n\n## Verifying CI Before Merge\n\nBefore merging the Version Packages PR, verify all CI checks pass:\n\n```bash\ngh pr checks \u003cpr-number> --json name,state,conclusion\n```\n\nAll checks must show `state: completed` and `conclusion: success`.\n\nIf checks are still running, use the `Monitor` tool (see `references/ci-polling.md`) to wait for them to complete.\n\n## Merging the Version Packages PR\n\nYELLOW-tier within autoship: invoking the skill is standing consent for the merge. Do not prompt for re-confirmation. Gate the merge with these objective preconditions instead.\n\nPreconditions (all must hold):\n\n- PR title is exactly \"Version Packages\" OR head branch is `changeset-release/main`. Never merge a PR that does not match.\n- All checks on the PR show `state: completed` and `conclusion: success` (verify with `gh pr checks \u003cpr-number> --json name,state,conclusion`).\n- PR is mergeable: `mergeable: MERGEABLE` (not `CONFLICTING` or `UNKNOWN`). If `UNKNOWN`, wait briefly and re-query.\n\nAnnounce in one short line, then execute:\n\n```text\nMerging Version Packages PR #\u003cn> — \u003cpackage>@\u003cversion>\n```\n\n```bash\ngh pr merge \u003cpr-number> --squash --delete-branch\n```\n\nPrefer `--squash` for clean history. Use `--merge` if the project convention requires merge commits.\n\nIf any precondition fails, stop and report to the user. Do not attempt to fix mergeability or override failing checks.\n\n## Watching the Publish Run\n\nAfter merging the Version Packages PR, the push to the default branch triggers the SAME release workflow again. This second run detects there are no pending changesets and executes the `publish:` script (`changeset publish`).\n\n### Detecting the Workflow Run\n\nFind the workflow file by inspecting `.github/workflows/` — common names are `release.yml`, `npm-publish.yml`, `publish.yml`. Then:\n\n```bash\n# Replace release.yml with the actual file name\ngh run list --workflow release.yml --branch main --limit 3 --json status,conclusion,databaseId,createdAt\n\n# Or list all recent runs and identify by name\ngh run list --branch main --limit 5 --json workflowName,status,conclusion,databaseId\n```\n\n### Watching for Completion\n\nStart a `Monitor` watch on the release workflow's latest run on `main`. See the \"Watching the Publish Workflow\" snippet in `references/ci-polling.md` for a ready-to-use script. The Monitor exits on the first `TERMINAL:` line.\n\nTerminal conditions:\n\n- **Success:** Workflow completes with `conclusion: success` -- report and stop\n- **Failure:** Workflow completes with `conclusion: failure` -- report with logs and stop\n- Do NOT auto-retry publish failures. These typically indicate real issues (auth, registry, permissions)\n\n### Verifying the Published Version\n\nAfter the publish workflow succeeds:\n\n```bash\nnpm view \u003cpackage-name> version\n```\n\nCompare with the version in `package.json` to confirm the publish was successful.\n\n## Cleanup\n\n- The `--delete-branch` flag on merge handles branch cleanup\n- Stop any `Monitor` watches that are still running\n- Report the final published version to the user\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6377,"content_sha256":"4bf332807e17141a1cfe6f91aa956a1f5066eb5d1bed4e604455780a81bd3104"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Autoship","type":"text"}]},{"type":"paragraph","content":[{"text":"Automate npm releases with a changeset -> fix -> push -> monitor -> merge -> publish workflow.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference Files","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"File","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Read when","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/changeset-and-commit.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Creating a changeset, fixing quality issues, or committing and pushing","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/ci-polling.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Watching CI with the Monitor tool, diagnosing failures, or handling retries","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/version-pr-and-publish.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Searching for the Version Packages PR, merging it, or watching the release workflow","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Intent Map","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Intent","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Steps","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Notes","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Full autoship (ship / release / publish)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1 through 5","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Default entry point. Runs end-to-end through publish without intermediate prompts","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Create changeset only","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Step 1","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Stage a release without pushing","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fix quality and push","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Steps 1-2","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Changeset + fixes + commit, no CI watch","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Watch CI only","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Steps 3-5","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When changes are already pushed","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Merge version PR only","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Steps 4-5","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When CI already passed. Auto-merges once preconditions are met","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fix compiler only","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Step 2","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When build is broken, no changeset needed","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Safety Tiers","type":"text"}]},{"type":"paragraph","content":[{"text":"Invoking autoship is standing consent for the full release flow. Do not pause mid-flow for re-confirmation; gate risky steps with objective preconditions instead.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GREEN -- execute directly:","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"gh run list","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"gh run view","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"gh pr list","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"gh pr checks","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"npm view","type":"text","marks":[{"type":"code_inline"}]},{"text":", reading CI status, listing changesets, reading ","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" scripts, ","type":"text"},{"text":"git log","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"git status","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"YELLOW -- announce then execute:","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"npm run changeset","type":"text","marks":[{"type":"code_inline"}]},{"text":" / writing changeset files, running lint/typecheck/test/format fixers, ","type":"text"},{"text":"git add/commit/push","type":"text","marks":[{"type":"code_inline"}]},{"text":", starting ","type":"text"},{"text":"Monitor","type":"text","marks":[{"type":"code_inline"}]},{"text":" background watches, and ","type":"text"},{"text":"gh pr merge","type":"text","marks":[{"type":"code_inline"}]},{"text":" of the Version Packages PR opened by ","type":"text"},{"text":"changesets/action","type":"text","marks":[{"type":"code_inline"}]},{"text":" once its identity is confirmed and all checks are green.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"RED -- explicit confirmation required:","type":"text","marks":[{"type":"code_inline"}]},{"text":" force-pushing, history rewrites, and any destructive git operations.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"Copy this checklist to track progress:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"Autoship progress:\n- [ ] Step 1: Create changeset (default patch)\n- [ ] Step 2: Fix lint, types, tests, format\n- [ ] Step 3: Commit + push changeset (do NOT run `changeset version`)\n- [ ] Step 4: Monitor CI and find/merge the Version Packages PR\n- [ ] Step 5: Watch release workflow to completion","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Create changeset (default patch)","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Load ","type":"text"},{"text":"references/changeset-and-commit.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check for existing pending changesets: ","type":"text"},{"text":"ls .changeset/*.md 2>/dev/null | grep -v README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If changesets exist, ask the user whether to create an additional one or skip.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Default to ","type":"text"},{"text":"patch","type":"text","marks":[{"type":"code_inline"}]},{"text":" bump type. Only use ","type":"text"},{"text":"minor","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"major","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the user explicitly requests it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Write the changeset file directly for non-interactive agent mode.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Infer the changeset summary from recent commits with ","type":"text"},{"text":"git log --oneline -10","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Fix lint, types, tests, format","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Load ","type":"text"},{"text":"references/changeset-and-commit.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (skip when running Fix compiler only intent).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-discover build/typecheck command: check ","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" scripts for ","type":"text"},{"text":"build","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"typecheck","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tsc","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"type-check","type":"text","marks":[{"type":"code_inline"}]},{"text":"; also check for ","type":"text"},{"text":"Makefile","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Cargo.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"pyproject.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"go.mod","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Discover available scripts from ","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run quality gates in order: lint, typecheck, test, format.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scope auto-fixers (","type":"text"},{"text":"lint --fix","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"format","type":"text","marks":[{"type":"code_inline"}]},{"text":") to changed files where the tool supports it. After any fixer runs, check ","type":"text"},{"text":"git status","type":"text","marks":[{"type":"code_inline"}]},{"text":" — broad ","type":"text"},{"text":"format","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" scripts routinely reformat or corrupt files outside your change (MDX is a frequent casualty). Revert anything unrelated (","type":"text"},{"text":"git restore \u003cpath>","type":"text","marks":[{"type":"code_inline"}]},{"text":") before continuing; never let a fixer's unrelated churn ride along in the release commit.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If any gate fails, parse error output to extract file, line, error code, and message. Prioritize: syntax errors first, then type errors, then lint errors.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Fix one error at a time when errors cascade (one root cause produces many symptoms).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Retry each gate up to 5 iterations after applying fixes. Report remaining error count each iteration.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a gate still fails after retries, stop and report to the user.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Commit + push changeset","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Stage the changeset file and the in-scope auto-fixes only — prefer ","type":"text"},{"text":"git add \u003cpaths>","type":"text","marks":[{"type":"code_inline"}]},{"text":" over ","type":"text"},{"text":"git add -A","type":"text","marks":[{"type":"code_inline"}]},{"text":". Before committing, run ","type":"text"},{"text":"git status --porcelain","type":"text","marks":[{"type":"code_inline"}]},{"text":" and strip stray generated artifacts (e.g. a root ","type":"text"},{"text":"schema.gql","type":"text","marks":[{"type":"code_inline"}]},{"text":" left by a pre-commit hook) and any unrelated files a fixer touched. Commit and push.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do NOT run ","type":"text"},{"text":"npx changeset version","type":"text","marks":[{"type":"code_inline"}]},{"text":" locally. CI's ","type":"text"},{"text":"changesets/action","type":"text","marks":[{"type":"code_inline"}]},{"text":" runs it inside the Version Packages PR.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The pushed commit must contain the pending ","type":"text"},{"text":".changeset/*.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" file so CI's \"Changeset Status\" check passes.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Monitor CI and find/merge the Version Packages PR","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Load ","type":"text"},{"text":"references/ci-polling.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"references/version-pr-and-publish.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"After pushing, start a ","type":"text"},{"text":"Monitor","type":"text","marks":[{"type":"code_inline"}]},{"text":" watch that emits a line each time the latest workflow run on the current branch reaches a terminal state (","type":"text"},{"text":"completed","type":"text","marks":[{"type":"code_inline"}]},{"text":"). The agent reacts to each emitted line; no ","type":"text"},{"text":"/loop","type":"text","marks":[{"type":"code_inline"}]},{"text":" re-prompt needed.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not stop prematurely. A single idle snapshot does not mean CI is done — keep the monitor running until at least one workflow run reports ","type":"text"},{"text":"completed","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"On failure: read logs, classify as flaky or real. Retry flaky failures up to 3 times with ","type":"text"},{"text":"gh run rerun \u003cid> --failed","type":"text","marks":[{"type":"code_inline"}]},{"text":". For real failures: fix, commit, push, restart the monitor.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Once CI is green, search for an open PR titled \"Version Packages\" or on branch ","type":"text"},{"text":"changeset-release/main","type":"text","marks":[{"type":"code_inline"}]},{"text":". If not found immediately, start a second ","type":"text"},{"text":"Monitor","type":"text","marks":[{"type":"code_inline"}]},{"text":" watch that polls for the PR for up to 10 minutes (the changesets bot needs time).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Before merging, verify ALL of the following preconditions:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"PR title is exactly \"Version Packages\" OR head branch is ","type":"text"},{"text":"changeset-release/main","type":"text","marks":[{"type":"code_inline"}]},{"text":" (do not merge any other PR).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every check on the PR shows ","type":"text"},{"text":"state: completed","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"conclusion: success","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"PR is mergeable (","type":"text"},{"text":"mergeable: MERGEABLE","type":"text","marks":[{"type":"code_inline"}]},{"text":", not ","type":"text"},{"text":"CONFLICTING","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"UNKNOWN","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Announce in one short line (\"Merging Version Packages PR #N — \u003cpackage>@\u003cversion>\"), then merge with ","type":"text"},{"text":"gh pr merge \u003cnumber> --squash --delete-branch","type":"text","marks":[{"type":"code_inline"}]},{"text":". Do not pause for confirmation; invoking autoship is the consent.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If any precondition fails, stop and report — do not merge.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5: Watch the publish run to completion","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Load ","type":"text"},{"text":"references/version-pr-and-publish.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"references/ci-polling.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Merging the Version Packages PR triggers the SAME release workflow again. Because no pending changesets remain, ","type":"text"},{"text":"changesets/action","type":"text","marks":[{"type":"code_inline"}]},{"text":" now executes the ","type":"text"},{"text":"publish:","type":"text","marks":[{"type":"code_inline"}]},{"text":" script (","type":"text"},{"text":"changeset publish","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify the workflow file (commonly ","type":"text"},{"text":"release.yml","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"npm-publish.yml","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"publish.yml","type":"text","marks":[{"type":"code_inline"}]},{"text":") in ","type":"text"},{"text":".github/workflows/","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Start a ","type":"text"},{"text":"Monitor","type":"text","marks":[{"type":"code_inline"}]},{"text":" watch on that workflow's latest run on ","type":"text"},{"text":"main","type":"text","marks":[{"type":"code_inline"}]},{"text":", emitting a line when it reaches a terminal state.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Terminal conditions: workflow succeeds (report published version) or fails (report with logs).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do NOT auto-retry publish failures. These typically need human investigation (npm auth, registry, OIDC/provenance, tag conflict).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"On success, verify with ","type":"text"},{"text":"npm view \u003cpackage> version","type":"text","marks":[{"type":"code_inline"}]},{"text":" and stop any remaining ","type":"text"},{"text":"Monitor","type":"text","marks":[{"type":"code_inline"}]},{"text":" watches.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Anti-patterns","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Running ","type":"text"},{"text":"npm publish","type":"text","marks":[{"type":"code_inline"}]},{"text":" directly instead of using the changesets workflow.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Merging the Version Packages PR before its CI checks pass.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Stopping CI monitoring after the first poll shows no runs (workflows take time to queue).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Creating a changeset with ","type":"text"},{"text":"major","type":"text","marks":[{"type":"code_inline"}]},{"text":" bump without explicit user instruction.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Force-pushing to the default branch.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-retrying publish failures (these are typically real auth, registry, OIDC/provenance, or tag-conflict issues).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Polling tighter than ~30s, which wastes GitHub API rate limit. Monitor scripts should ","type":"text"},{"text":"sleep 30","type":"text","marks":[{"type":"code_inline"}]},{"text":" or longer between ","type":"text"},{"text":"gh","type":"text","marks":[{"type":"code_inline"}]},{"text":" calls.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Never run ","type":"text","marks":[{"type":"strong"}]},{"text":"npx changeset version","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" locally.","type":"text","marks":[{"type":"strong"}]},{"text":" CI's ","type":"text"},{"text":"changesets/action","type":"text","marks":[{"type":"code_inline"}]},{"text":" runs it inside the Version Packages PR. Running it locally consumes the changeset file, the pushed commit has no pending changeset, CI's \"Changeset Status\" check fails, and no Version Packages PR is opened.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hand-editing ","type":"text"},{"text":"CHANGELOG.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"package.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"version","type":"text","marks":[{"type":"code_inline"}]},{"text":" as part of autoship — CI generates both.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Letting a ","type":"text"},{"text":"format","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" script reformat or corrupt files outside your change (e.g. MDX) — scope fixers to changed files and revert unrelated churn before committing.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Committing stray generated artifacts (e.g. a root ","type":"text"},{"text":"schema.gql","type":"text","marks":[{"type":"code_inline"}]},{"text":") emitted by a pre-commit hook — sweep ","type":"text"},{"text":"git status","type":"text","marks":[{"type":"code_inline"}]},{"text":" and stage only intended files.","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"autoship","author":"@skillopedia","source":{"stars":40,"repo_name":"agent-skills","origin_url":"https://github.com/mblode/agent-skills/blob/HEAD/skills/autoship/SKILL.md","repo_owner":"mblode","body_sha256":"a9d5130575a9029e75f18ab3b4025b59ae3ff4119d72856b958668e59b6470d0","cluster_key":"3d68f2c53639cfe7c2913552a6e5a5a29824d5aed85e3d604795b27c6e9ec51b","clean_bundle":{"format":"clean-skill-bundle-v1","source":"mblode/agent-skills/skills/autoship/SKILL.md","attachments":[{"id":"08762f5d-1706-5833-8758-ca6d2b0bde79","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/08762f5d-1706-5833-8758-ca6d2b0bde79/attachment.md","path":"references/changeset-and-commit.md","size":3079,"sha256":"d2b46b5b65da4727436b29e84602d61dae6251d3cec67a77d3613c5346328a70","contentType":"text/markdown; charset=utf-8"},{"id":"2252410a-76eb-58fc-abe3-38a7ea393cbd","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2252410a-76eb-58fc-abe3-38a7ea393cbd/attachment.md","path":"references/ci-polling.md","size":6217,"sha256":"fa64ebaed6e1048c2ef5990438e30bd2da696422927be5502b4fb48709aaed99","contentType":"text/markdown; charset=utf-8"},{"id":"e82c0d18-f419-59b4-bf7a-6a55ace4cdf8","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/e82c0d18-f419-59b4-bf7a-6a55ace4cdf8/attachment.md","path":"references/version-pr-and-publish.md","size":6377,"sha256":"4bf332807e17141a1cfe6f91aa956a1f5066eb5d1bed4e604455780a81bd3104","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"499463cceb03b7a974994ad47037cdd5d6f883a78ce7f79f41e2a4251e2cae69","attachment_count":3,"text_attachments":3,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/autoship/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"testing-qa","category_label":"Testing"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"testing-qa","import_tag":"clean-skills-v1","description":"Automates npm release workflows using changesets. Creates a changeset (default patch), fixes lint/test/typecheck/format issues with an iterative compile-fix loop, commits and pushes, watches CI via the Monitor tool, finds and merges the Version Packages PR opened by changesets/action, and watches the release workflow to completion. Use when the user asks to ship, release, publish, autoship, cut a release for an npm package, fix compiler errors, fix type errors, make it compile, or fix the build."}},"renderedAt":1782980756040}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.