Ship Notes Skill

Overview

Generates periodic ":ship: Ship" notes for your team. Reads configuration from config.yml in this skill directory, pulls merged work from the last 14 days across all configured repos, groups it thematically into your defined categories, drafts narrative bullets, asks clarifying questions, then produces the final Slack-ready output.

Announce at start: "I'm using the ship-notes skill to draft your ship notes."

When to Use

• User asks to draft ship notes, sprint summary, or periodic update
• Trigger phrases: "draft ship notes", "write the ship update", "bi-weekly summary", "sprint notes", "/ship-notes"

Step 1: Load Config

Read config.yml from this skill's directory. If it doesn't exist, run the setup wizard (see bottom of this file) before proceeding.

Step 2: Sync All Repos

For each repo defined in config, ensure it's on the configured branch and up to date:

git -C [path] checkout [branch] && git -C [path] pull

If any pull fails or reports conflicts, stop and let the user know before continuing.

Step 3: Gather Git History

For each repo in config, run:

git -C [path] log \
  --format="%h %s" --since="14 days ago" \
  [-- scope/path/if/defined] \
  | grep -v "[noise_filter_1]\|[noise_filter_2]..."

Also check for recent release tags:

git -C [path] tag --sort=-version:refname | head -5

Step 4: Gather Closed GitHub Issues

For each repo where issues.enabled is true, pull issues closed in the last 14 days as a supplementary source. This catches research, discovery, design work, and planning that produces few or no commits.

If gh_host is set in config, prefix all gh commands with GH_HOST=[gh_host].

If the repo has gh_team set, first resolve the team members dynamically:

gh api orgs/[org]/teams/[team-slug]/members --hostname va.ghe.com --jq '.[].login'

Then fetch closed issues assigned to any of those members:

GH_HOST=va.ghe.com gh issue list --repo [gh_repo] --state closed \
  --search "closed:>=$(date -v-14d +%Y-%m-%d) assignee:[member1] assignee:[member2]..." \
  --json title,number,closedAt,assignees,labels \
  --limit 50

If the repo has a static assignees list, use those directly in the same command.

If neither is set (small/focused repo), pull all closed issues without an assignee filter:

GH_HOST=va.ghe.com gh issue list --repo [gh_repo] --state closed \
  --search "closed:>=$(date -v-14d +%Y-%m-%d)" \
  --json title,number,closedAt,assignees,labels \
  --limit 50

Use issue titles and bodies as supplementary context when drafting bullets — especially for categories like AI Initiatives, Design & Documentation, and Accessibility where work is often tracked in issues rather than commits. Don't create a separate "Issues" section; fold this information into the appropriate categories alongside the git history.

Step 5: Draft Thematic Bullets

Group all commits across all repos into the categories defined in config.yml. Use the category description field to decide what belongs where.

Audience: BU leadership (VPs, PgMs), practice leadership (Directors, Practice Leads), executive leadership, and — most importantly — other practitioners on peer programs. Write for a smart colleague who doesn't follow your team's work day-to-day. Every bullet should be interpretable without knowing your sprint plan or ticket backlog.

Keep:

• Features shipped and their impact to VA and Veterans — e.g. "New VA.gov homepage rolled out to 100% of users"
• New patterns or components available for other teams to use
• Significant fixes that unblocked consuming teams or improved the Veteran experience
• Completed discovery that shapes future direction for the program or platform
• Team updates with impact outside your program — e.g. "Team A launched X which will be used by Y program to do Z"

Drop:

• Ticket-level updates ("finished round 1 of designs", "closed 60 points")
• TypeScript errors, minor formatting, dep bumps, CI/workflow fixes, minor copy edits
• Metrics updates and pattern adherence automation
• Team updates not relevant to anyone outside your program (vacation, internal process changes)
• Lengthy narrative; no copy/paste of sprint reports

Writing rules:

• Do NOT list PRs by number — synthesize related commits into narrative bullets
• Write in first-person plural ("we added", "we fixed", "the team completed")
• Lead with Veteran or team impact: ask "what changed for Veterans or for teams building on VA.gov?"
• Be specific: "Fixed an accessibility issue" is too vague. Name the component, the page, the behavior that changed, and why it matters.
• Group related commits into one bullet — don't repeat the same component across multiple bullets
• Distinguish completed vs. in-progress work ("shipped X" vs. "completed discovery on X" vs. "continued work on X")
• Each item appears in only one category. If work touches another area, mention it in the bullet rather than duplicating it
• Include links where relevant — release notes, newly published guidance pages, ADRs, anything worth clicking through to
• Infer links from context where possible:
  • Doc site pages: combine doc_base_url from config with the file path (e.g. src/_components/breadcrumbs/design-decisions.md → [doc_base_url]/components/breadcrumbs/design-decisions)
  • For links you can't infer, ask the user at the end
• Release versions: always fetch GitHub release URLs via gh release list. Format the release bullet as: * vX.Y.Z was released [Month D, YYYY] ([Release notes](url)) Then add scannable sub-bullets (indented) for any changes from the release notes worth calling out — significant fixes, new features, or anything that affects consuming teams. Keep sub-bullets short and specific. If the local repo hasn't been tagged yet but the user mentioned a release, trust the user and note the link may not be live yet.

Step 6: Ask for Context, Challenges, and Shoutouts

Present the full draft first as one uninterrupted copyable block (all categories together, no questions in the text). Then ask these three things below the draft:

1. Context paragraph: "Do you have an opening paragraph — team news, contract updates, hellos/goodbyes? (Fine to skip.)"
2. Challenges/opportunities: "Any challenges or gaps worth calling out — things that surfaced a need or could become an opportunity?"
3. Shoutouts/wins: "Any shoutouts, feel-good moments, or wins to include?"
4. Links: "Do you have URLs for any items I couldn't link automatically?" (only ask if there are gaps)

Only ask questions where you genuinely need input. Don't ask about sections that are clear.

Step 7: Produce Final Output

:ship: [M/D/YYYY] Ship

[team_name from config]

[Context paragraph if provided — omit entirely if skipped]

[Category Name]
* [bullet]
* [bullet]

[Category Name]
* [bullet]

...

• Use today's date from currentDate context if available
• Category headings are plain text (not bold, not bullet points)
• Omit any category that has nothing to report after filtering noise
• The user will copy-paste this into Slack — keep formatting clean

Setup Wizard (run if config.yml is missing)

If config.yml doesn't exist in this skill's directory, tell the user:

"I don't see a config.yml for the ship-notes skill. Let me help you set one up — I'll ask a few questions and create it for you."

Then ask:

1. Team name: "What's your team or program name? (This appears in the header of every ship note)"
2. Repos: "What repos should I pull from? For each one, tell me: a name, the absolute path on your machine, and any subdirectory to scope to (or 'whole repo'). List as many as you have."
3. Noise filters: "Are there any commit message patterns I should always ignore? (e.g. 'dependabot', 'Merge branch', metrics updates — I'll suggest common ones based on what you tell me about your repos)"
4. Categories: "What categories do you want to report on? For each one, give me a name and a short description of what kind of work belongs there."
5. Doc site: "Do you have a documentation site I can use to generate links? If so, what's the base URL?"

Write the answers to config.yml using the structure in config.example.yml, then proceed with Step 2.