agentleFS
fworks-techfworks-tech/agenthood/skills/herald/SKILL.md

herald

Skill2 starsChanged todayMITView on GitHub

Manages semantic versioning, release notes, changelog generation, and scheduled reports. Use before every release to determine the version bump and generate changelog. Use for daily standups and end-of-day summaries.

  • Commits and pushes

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 5 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before every release — to determine version bump and generate changelog

    line 16
  2. Distinctive:

    When preparing a GitHub Release

    line 17
  3. Distinctive:

    When a stakeholder asks "what shipped this week?"

    line 20
  4. Very specific:

    Run git log <last-tag>..HEAD --oneline to list commits since last release

    line 26
  5. Distinctive:

    Create a git tag: git tag v1.3.0

    line 69
  6. Distinctive:

    Create a GitHub Release:

    line 71
  7. Very specific:

    Every agenthood run writes a decision + provenance entry to .agenthood/decisions/ and .agenthood/provenance/ (ADR-015).

    line 119

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

The Herald

Overview

The Herald does not release code. It announces it. Every release has a version number that means something. Every release has notes that humans can read. Every release was earned — by passing tests, clean commits, and a merged PR. The Herald makes sure everyone knows when something ships, what changed, and what it means.

When to Use

  • Before every release — to determine version bump and generate changelog
  • When preparing a GitHub Release
  • Daily at 8:00 AM — morning standup report
  • Daily at end of day — work summary
  • When a stakeholder asks "what shipped this week?"

Process

Semantic Version Determination

  1. Run git log <last-tag>..HEAD --oneline to list commits since last release
  2. Scan commit types to determine the version bump:
Commit type foundVersion bumpExample
Any feat! or BREAKING CHANGE footerMajor 1.0.0 → 2.0.0New API incompatibility
Any feat (no breaking change)Minor 1.0.0 → 1.1.0New capability
Only fix, perf, no featPatch 1.0.0 → 1.0.1Bug fixes only
Only chore, docs, ci, testNo bumpInternal only
  1. Announce the determination with reasoning: "Next version: 1.3.0 (minor bump) — 2 feat commits found since v1.2.1."

Changelog Generation

  1. Group commits since last tag by type
  2. Filter: include feat, fix, perf, refactor (if user-visible). Exclude ci, chore, test, docs (internal)
  3. Translate technical subjects to user-facing language:
    • fix(api): handle null response from geocoding service → Fixed an issue where route planning could fail when the location service was unavailable
    • feat(ui): add dark mode toggle → Added a dark mode toggle in the settings panel
  4. Format following Keep a Changelog:
## [1.3.0] - YYYY-MM-DD

### Added
- Description of new feature (#{PR number})

### Fixed
- Description of bug fix (#{PR number})

### Changed
- Description of changed behavior (#{PR number})

### Removed
- Description of removed feature (#{PR number})
  1. Prepend to CHANGELOG.md
  2. Link each entry to its PR

GitHub Release

  1. Create a git tag: git tag v1.3.0
  2. Push the tag: git push origin v1.3.0
  3. Create a GitHub Release:
    • Title: v1.3.0 — Month Day, Year
    • Body: the formatted changelog section for this version
    • Link: "Full changelog: CHANGELOG.md#130"

Morning Standup Report

Generated at 8:00 AM from git activity since yesterday:

## Morning Briefing — {Date}

### Merged Yesterday
- #{PR} feat(ui): add dark mode toggle
- #{PR} fix(api): handle geocoding null response

### Open PRs Awaiting Review
- #{PR} feat(auth): add OAuth2 login (2 days open)

### In Progress (branches with recent commits)
- fix/issue-102-login-redirect (last commit 3h ago)

### ⚠️ Attention
- Branch feat/old-experiment has not been updated in 5 days
- 14 uncommitted changes in src/components/Map.tsx (2h idle)

End of Day Summary

Generated at end of working session:

## End of Day — {Date}

### Completed
- Closed #{issue} — fix login redirect loop
- Merged #{PR} — feat(ui): dark mode toggle

### In Progress
- #{issue} — OAuth2 integration (spec written, implementation 40%)

### Tomorrow
- Complete OAuth2 implementation
- Review #{PR} from teammate

Decision-Aware Reporting

Every agenthood run writes a decision + provenance entry to .agenthood/decisions/ and .agenthood/provenance/ (ADR-015). When the Herald's reports need the why behind merged work, read the decision log and its causal edges (edges.json) — the changelog can cite the recorded decision behind each change instead of guessing from commit subjects.

Red Flags

  • A release with no changelog entry
  • A version bump that doesn't match the commit types present
  • CHANGELOG.md last updated more than 2 releases ago
  • A GitHub Release with no description
  • PRs open for more than 3 days without review

Rationalizations

What you thinkWhat The Herald knows
"Everyone knows what changed"Nobody reads commits. People read changelogs. Write the changelog.
"The version number doesn't matter"It matters to every consumer of your API, package, or service.
"We'll update the changelog before launch"The changelog is hardest to write the furthest you are from the changes. Write it as you go.

Verification

Before a release:

  • Version bump is correct for the commit types present
  • CHANGELOG.md is updated with user-facing language
  • Git tag is created and pushed
  • GitHub Release is created with formatted notes
  • All entries link to their PRs
  • Breaking changes are prominently marked

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.