Ship

Ship Skill

Automates the full cycle: update documentation, stage, commit, push, and sweep temp files. Groups related changes into one commit per topic and handles the doc catch-up path when the working tree is clean but commits are unpushed.

Workflow

Step 1: Review changes

Run all three commands to get the full picture:

git status --short
git diff --cached --name-status
git log @{upstream}..HEAD --oneline 2>/dev/null

Also identify the current branch and remote tracking status:

git branch --show-current
git rev-parse --abbrev-ref @{upstream} 2>/dev/null

Classify uncommitted changes from git status:

• M — modified, ?? — untracked, D — deleted, R — renamed

If the working tree is clean but unpushed commits exist, this is the doc catch-up path:

1. Run git diff @{upstream}..HEAD --name-status to list all files changed in unpushed commits
2. Analyze those files in Step 2 as if they were uncommitted changes
3. Proceed to Step 3 to check for missing documentation updates (CHANGELOG, README, CLAUDE.md, marketplace.json)
4. If documentation updates are needed, make them, commit, and push
5. If no documentation updates are needed, just push

If both the working tree is clean AND no unpushed commits exist, report "nothing to ship" and stop.

Step 2: Analyze what changed

Read every modified/untracked file (or every file from unpushed commits in the doc catch-up path) to understand the nature of the changes.

Step 3: Update documentation

For each applicable documentation file, read the current contents first, then update.

CHANGELOG.md

• When: Always, if the file exists in the repo root
• Format: Follow Keep a Changelog
• Add a new ## [YYYY-MM-DD] section (today's date) at the top of the log
• If today's date section already exists, append to it instead of creating a duplicate
• Subsections: Added, Changed, Removed, Fixed — only include relevant ones
• Each entry: one concise line describing the change from a user/reader perspective

CLAUDE.md (always run)

• When: Always. Read CLAUDE.md and compare against the current project state — not just the changes being shipped, but also decisions made during the session, new or renamed files on disk, and structural changes
• Skip when: Changes are limited to content additions (e.g., adding a link to Resources) AND no session-level decisions or structural changes occurred
• Update only the affected sections — do not rewrite the entire file
• Check for temporal markers (e.g., "Current position," dates, deadlines, status tables) that may be stale given the changes being shipped

README files (root or section-level)

• When: Changes affect content described by that README
• Examples: adding a notebook -> update the directory's README; renaming a section -> update root README
• Skip when: The change is self-evident from the file itself (e.g., adding a row to a resource table — the table IS the README)

Cascade check (skip if no scripts or data files changed)

If any modified files are scripts or data files:

• Identify downstream files: Find all markdown reports, appendices, and documentation that reference outputs or data from the modified files — search for filename references, table headers, variable names, and output patterns
• Verify consistency: Check that numbers, table data, file paths, and cross-references in downstream files match the current state of the modified scripts and their outputs
• Fix discrepancies: Update any stale numbers, outdated references, or mismatched data in downstream files. Include these fixes in the commit

Stale and missing reference check

After identifying all changed, added, and deleted files, check documentation files for stale or missing references:

• Deleted files: Search README.md, CLAUDE.md, and any doc that might reference them (folder trees, file lists, dependency mentions)
• Renamed/moved files: Update all path references
• Removed features or dependencies: Remove or update mentions in all docs
• New directories or files: If CLAUDE.md or README.md contain folder trees, check whether newly added directories or files should appear in those trees
• Run: git diff --name-status to get the full list of added (A/??), deleted (D), and renamed (R) files, then search docs for entries that need adding or removing