seggwat-changelog — SeggWat Agent Skill

Turn a release (a tag or a commit range) into customer-facing entries on the project's public SeggWat changelog. Entries always land as drafts. They're published only after the user explicitly says so.

Changelog tools exist only on the MCP server. The seggwat CLI has no changelog commands. Git and gh supply the input.

Connect

bash

# OAuth: no token needed, run /mcp in Claude Code afterwards to sign in
claude mcp add --transport http seggwat https://seggwat.com/mcp

# Or a static Organization Access Token (headless, CI)
claude mcp add --transport http seggwat https://seggwat.com/mcp \
  --header "Authorization: Bearer $SEGGWAT_API_KEY"

The entry model

Field	Notes
`title`	Required. Short headline: "Export to Excel", not a commit subject
`body`	Markdown, rendered on the public board
`version`	Semver with a `v` prefix, taken from the release tag (`v1.4.0`). Pure version only, no date or codename
`category`	One of `added`, `improved`, `fixed`, `changed`, `removed`, `security`
`component`	Optional slug from the project's component registry (`cli`, `react-sdk`). An unknown slug errors and lists the valid ones
`status`	`draft` (default), `published`, or `hidden`
`source`	`manual` for entries you create. `github_release` and `completed_idea` drafts can appear on their own

One release = one entry per user-facing change, all with the same version (and the same component, if the project uses components). The board renders them as one release block, with a category badge on each change. An entry holds only one category, so a single combined entry would lose the badges. If the user wants a single entry anyway, set its category to whichever kind of change dominates the release.

Workflow

1. Resolve the project and check for existing entries

list_projects {}
list_changelog { "project_id": "<id>" }
list_changelog { "project_id": "<id>", "component": "cli" }   # monorepo with components

list_changelog returns every status, newest first. If entries already exist for this version (and component), reconcile per change: update the draft that covers a change with update_changelog_entry, create entries only for changes that have none, and never create a second entry for the same change. That way a rerun after a partial failure completes the release instead of duplicating it. Common case: the project syncs GitHub releases, so a github_release draft for the tag already exists; rewrite it to cover the first change. Only touch drafts; a published entry changes only when the user asks.

2. Pick the range

From a tag:

bash

TAG=v1.4.0
PREV=$(git describe --tags --abbrev=0 --match 'v*' "$TAG^" 2>/dev/null)   # empty on the first release
git log --no-merges --format='%h %s%n%b' "${PREV:+$PREV..}$TAG"

--match keeps tags of other products in a monorepo from shortening the range. For component-prefixed tags such as cli-v1.4.0, use --match 'cli-v*' and set version to the part after the prefix (v1.4.0).

No tag yet: start from the newest published entry's published_at in list_changelog:

bash

git log --no-merges --since="2026-09-12" --format='%h %s%n%b'
gh pr list --state merged --search "merged:>2026-09-12" --json number,title,body --limit 100

Then propose the next semver from that entry's version and the changes in range: a ! or BREAKING CHANGE: bumps major, a feat bumps minor, only fix/perf bumps patch. Confirm the number with the user before using it as version.

3. Group by Conventional Commit type

Commit	Category	Keep?
`feat` (new capability)	`added`	yes
`feat` (better existing capability), `perf`	`improved`	yes
`fix`	`fixed`	yes
`!` or a `BREAKING CHANGE:` footer	`changed`, or `removed` if something went away	always
security fix	`security`	always
`chore`, `ci`, `docs`, `test`, `build`, `refactor`, `style`	—	drop, unless users notice the change

Merge commits that describe one user-visible change into a single entry. Drop anything internal-only.

4. Write for customers

Say what changed for the user, and where to find it, in the present tense: "You can now export feedback as an Excel file from the Export menu."
Don't include commit hashes, PR numbers, ticket ids, internal module names, or author names.
Breaking changes say exactly what the user has to do.
1 to 3 sentences per entry. Bullets only when a change has several parts.

5. Create as drafts

Use one call per change. Never pass publish: true.

create_changelog_entry {
  "project_id": "<id>",
  "title": "Export to Excel",
  "body": "You can now export feedback as an `.xlsx` file from the **Export** menu, next to CSV.",
  "version": "v1.4.0",
  "category": "added"
}

Then show the user the full draft set as Markdown, grouped by category, with each entry's id.

6. Edit, then publish only on an explicit yes

Edits:

update_changelog_entry { "project_id": "<id>", "entry_id": "<eid>", "body": "<new markdown>" }

Only the fields you pass change. Pass "" to clear version, category, or component.

Publish only after the user says to publish (for example "publish it" or "ship the v1.4.0 notes"). Approving the wording isn't approval to publish:

set_changelog_status { "project_id": "<id>", "entry_id": "<eid>", "status": "published" }

Call it once per entry. draft unpublishes, and hidden soft-hides without deleting.

7. Optional: close the loop on feedback

Find feedback the release addressed:

bash

git log --format='%h %s%n%b' "$PREV..$TAG" | grep -iE 'feedback[: #]*[0-9a-f]{24}'

get_feedback  { "project_id": "<id>", "feedback_id": "<fid>" }               # confirm it exists and is still open
list_feedback { "project_id": "<id>", "search": "excel export", "status": "Active" }   # title-less match by keyword

Matching by keyword gives you candidates only. List them for the user, and don't act on them yourself.

Resolving emails the submitter, and the note goes into that email. So do it only after the entries are published and the user confirms the list:

update_feedback {
  "project_id": "<id>", "feedback_id": "<fid>",
  "status": "Resolved",
  "resolution_note": "Fixed in v1.4.0: large PNG uploads no longer crash. Thanks for reporting it!"
}

Write the note for the end user. Don't paste an internal id or a link you haven't verified. MCP returns no public changelog URL, so "see our changelog" is enough.

Rules

Always draft first. Never use publish: true, and never call set_changelog_status with published without an explicit instruction.
Check before creating. Before writing anything, read list_changelog. Existing entries for the version are reconciled per change: update the matching draft, create only what is missing, never duplicate. Only update drafts; a published entry changes only when the user asks for it.
One release block per version. Every entry for a release shares version (and component).
Customer prose only. Commit messages are input, not output.
Resolve feedback only after publishing, and only with confirmation. It sends email.
Never delete changelog entries or feedback. Use hidden for entries.

Automate on release tags

This runs on every v* tag and leaves drafts for a human to publish. Install the skill into the repo (npx skills add SeggWat/cli-seggwat --skill seggwat-changelog lands it in .agents/skills/ with a .claude/skills/ symlink) and commit it so headless Claude Code finds it. Add the SEGGWAT_API_KEY repository secret plus ANTHROPIC_API_KEY, or CLAUDE_CODE_OAUTH_TOKEN from claude setup-token to bill a Claude subscription instead.

yaml

# .github/workflows/changelog-draft.yml
name: Changelog draft
on:
  push:
    tags: ['v*']

permissions:
  contents: read

jobs:
  draft:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # full history and tags for git describe/log

      - name: Install Claude Code
        run: |
          curl -fsSL https://claude.ai/install.sh | bash
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Draft SeggWat changelog
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          SEGGWAT_API_KEY: ${{ secrets.SEGGWAT_API_KEY }}
          TAG: ${{ github.ref_name }}
        run: |
          set -o pipefail
          cat > "$RUNNER_TEMP/mcp.json" <<EOF
          {"mcpServers":{"seggwat":{"type":"http","url":"https://seggwat.com/mcp",
            "headers":{"Authorization":"Bearer ${SEGGWAT_API_KEY}"}}}}
          EOF
          claude -p "Use the seggwat-changelog skill to draft changelog entries for tag $TAG in SeggWat project \"Acme Web\". Drafts only: do not publish and do not update feedback." \
            --mcp-config "$RUNNER_TEMP/mcp.json" \
            --output-format stream-json --verbose \
            --allowedTools "Bash(git describe:*)" "Bash(git log:*)" "Bash(git tag:*)" \
              "mcp__seggwat__list_projects" "mcp__seggwat__list_changelog" \
              "mcp__seggwat__create_changelog_entry" "mcp__seggwat__update_changelog_entry" \
            | tee "$RUNNER_TEMP/out.jsonl" | jq -r 'select(.type=="result") | .result'
          # Fail the run if Claude never reached the SeggWat MCP server.
          jq -e 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and (.name|startswith("mcp__seggwat__")))' \
            "$RUNNER_TEMP/out.jsonl" >/dev/null \
            || { echo "::error::Claude never called a SeggWat MCP tool: check the MCP connection and SEGGWAT_API_KEY"; exit 1; }

set_changelog_status and update_feedback are left off the allow list, so CI can't flip an entry to published or send email even if asked. create_changelog_entry still accepts publish: true; this skill never sets it, and the prompt says drafts only. A human reviews the drafts in the dashboard, or asks Claude to "publish the v1.4.0 notes".

The last jq is the safety net: a headless run prints a polite "the tools aren't available" message and exits 0 when the MCP server is unreachable or returns no tools, so without it the job goes green with nothing drafted. If the gate fires, rerun with --debug='mcp' --debug-file "$RUNNER_TEMP/mcp.log" and look for Failed to fetch tools.

Worked example

Input: git log --no-merges --format='%h %s' v1.3.2..v1.4.0

a1b2c3d feat(export): add XLSX export
d4e5f6a fix(upload): handle PNGs over 5MB (closes feedback 66f1c0a2e4b0c9d1a2b3c4d5)
0a9b8c7 perf(dashboard): cache project stats
99aabbc feat(api)!: remove v0 endpoints
1122334 chore(deps): bump tokio to 1.47
5566778 ci: cache cargo registry

list_changelog shows no entry with version: "v1.4.0". The chore and ci commits are dropped.

Drafts created (4 calls to create_changelog_entry, all version: "v1.4.0"):

markdown

## v1.4.0 (draft)

**Added** · Export to Excel
You can now export feedback as an `.xlsx` file from the **Export** menu, next to CSV.

**Fixed** · Large image uploads
Uploading PNG screenshots larger than 5 MB no longer fails.

**Improved** · Faster dashboard
Project dashboards load noticeably faster, especially for projects with a lot of feedback.

**Removed** · Legacy v0 API
The v0 API endpoints are gone. If you still call `/api/v0/...`, switch to the
equivalent `/api/v1/...` endpoint. Request and response shapes are unchanged.

Next, ask: "4 drafts created for v1.4.0. Publish them? Commit d4e5f6a references feedback 66f1c0a2e4b0c9d1a2b3c4d5 (Active). After publishing, should I resolve it with the note 'Fixed in v1.4.0: large PNG uploads no longer fail'? That emails the submitter."

Hit a problem with SeggWat itself?

report_problem { "category": "feature_gap", "title": "<one line>", "surface": "create_changelog_entry", "summary": "<what happened vs. expected>" }

category is one of bug, docs_mismatch, friction, feature_gap, quality_degradation, other. File one report per problem and keep going.