feat(skills): Add shepherd-prs skill for managing approved external contributor PRs by harryterkelsen · Pull Request #188534 · flutter/flutter

harryterkelsen · 2026-06-24T23:02:00Z

Description

This Pull Request adds the shepherd-prs skill to the repository. The skill is designed to help agentic coding assistants automate the shepherding and landing of approved third-party Pull Requests in the flutter/flutter repository.

Under the hood, it utilizes a self-contained, type-safe Dart command-line tool (scripts/shepherd.dart) that interacts with the GitHub and LUCI APIs via the gh CLI. It identifies approved PRs, checks their CI health and branch states, and performs necessary maintenance tasks (like branch updates and CI trigger re-runs) before safe integration.

Skill Usage Examples

Below are examples of user prompts, the agent's internal tool executions, and the resulting outputs:

Example 1: Retrieving and Summarizing PR Status

User Prompt:

"What is the status of my approved PRs?"

Agent Execution:
The agent loads the skill, executes the read-only list command, and parses the JSON response:

dart .agents/skills/shepherd-prs/scripts/shepherd.dart list

Agent Response:

You have 1 approved third-party PR requiring shepherding:

PR engine: explain why each candidate build was skipped in Flutter web loader #186254: Fix web image codec unification issues (by @External-Contributor)

Status: Clean of conflicts, all 4 CI checks passed.

Branch State: Behind the default branch by 52 commits.

Recommended Action: Update branch (bring up to date with main).

Would you like me to execute the branch update for PR #186254?

Example 2: Running Shepherding on a Specific PR

User Prompt:

"Yes, please update the branch for PR #186254."

Agent Execution:
Upon receiving explicit user confirmation, the agent runs the execution command:

dart .agents/skills/shepherd-prs/scripts/shepherd.dart run --pr 186254

Agent Response:

I have successfully triggered the branch update for PR #186254 (was behind by 52 commits). I will monitor the PR and let you know when the update is complete and CI starts running.

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

flutter-dashboard · 2026-06-24T23:02:05Z

It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging.

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group.

gemini-code-assist

Code Review

This pull request adds a shepherding skill and a self-contained Dart script (shepherd.dart) to automate updating and landing approved third-party pull requests in the flutter/flutter repository. The review feedback recommends passing the dynamic default branch name to the branch comparison API instead of hardcoding main. Additionally, the feedback suggests storing the head SHA directly in the PullRequest object to eliminate redundant sequential API calls when syncing state, which also allows the removal of the unused getPrHeadSha helper.

reidbaker

I see you have authored shepherd.dart as a script with no dependencies. Given we are still experimenting with standards lets land this using the structure you have defined. I think long term we will required that skills use a dart package (that has documentation, tests, dependencies and dependency management, analysis options etc) but this will be a good experiment.

reidbaker · 2026-06-30T16:14:21Z

+* Due to GitHub App permission policies, third-party check runs (such as LUCI checks created by `flutter-dashboard`) cannot be re-run via the API.
+* When a PR has failed checks, the tool will log a warning instructing you to ask the user to manually trigger the re-run via the GitHub web UI.
+* **Action**:
+  1. Print the warning and link the user to the PR on GitHub, asking them to click the "Re-run" button for the failed check.


This works until @ievdokdm lands his change to where reruns happen.

I'm not aware of those upcoming changes but if they allow re-running the tests via the GitHub API that would be amazing

If you look at recent prs you can no longer click rerun on the tasks in github. https://github.com/flutter/flutter/pull/188803/checks?check_run_id=84358870694

There is now a dashboard checker that looks at the flutter dashboard.

…ls.io spec

…proved PRs

…d open PRs

…n open PRs and approved third-party PRs

harryterkelsen · 2026-06-30T17:53:15Z

I see you have authored shepherd.dart as a script with no dependencies. Given we are still experimenting with standards lets land this using the structure you have defined. I think long term we will required that skills use a dart package (that has documentation, tests, dependencies and dependency management, analysis options etc) but this will be a good experiment.

I actually had it structured as a dart package (with a package:args dependency and tests) but put it into a standalone file to match what we had for the other skills in our repo.

harryterkelsen · 2026-06-30T17:53:28Z

Thanks @reidbaker! PTAL

reidbaker

Approved to get this in the hands of contributors.

There are still improvements I would make to this skill but I dont want to block this any longer and I am gone next week.

…12135) Manual roll Flutter from ca9f874f5284 to 6995038d96ef (44 revisions) Manual roll requested by stuartmorgan@google.com flutter/flutter@ca9f874...6995038 2026-07-03 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from sx_eN0J_f2BV6jqjW... to Jr08vyeibMSv3Oxst... (flutter/flutter#188946) 2026-07-03 engine-flutter-autoroll@skia.org Roll Packages from 420e135 to 2fbe873 (1 revision) (flutter/flutter#188945) 2026-07-03 engine-flutter-autoroll@skia.org Roll Dart SDK from 786212a2ce0d to 1f9a08ce0638 (4 revisions) (flutter/flutter#188944) 2026-07-03 engine-flutter-autoroll@skia.org Roll Skia from 5358ab75b840 to 919956953af6 (7 revisions) (flutter/flutter#188943) 2026-07-02 j.ihlas@betclicgroup.com [Windows] Keep regular windows in place when another is activated (flutter/flutter#188016) 2026-07-02 okorohelijah@google.com [flutter_tools] Provide guided message when iOS/macOS build fails due to low minimum version (flutter/flutter#188812) 2026-07-02 bdero@google.com [Flutter GPU] Load a ShaderLibrary from shader bundle bytes (flutter/flutter#188596) 2026-07-02 dacoharkes@google.com [tool] Enable record_use experiment by default on all channels (flutter/flutter#188887) 2026-07-02 engine-flutter-autoroll@skia.org Roll Packages from e742106 to 420e135 (13 revisions) (flutter/flutter#188916) 2026-07-02 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from I2h2eXk06RrA3pIG2... to sx_eN0J_f2BV6jqjW... (flutter/flutter#188915) 2026-07-02 256906086+mvincentong@users.noreply.github.com Clarify layout callback debug flag docs (flutter/flutter#186879) 2026-07-02 engine-flutter-autoroll@skia.org Roll Skia from 0c4faca350cc to 5358ab75b840 (2 revisions) (flutter/flutter#188899) 2026-07-02 engine-flutter-autoroll@skia.org Roll Dart SDK from e47361c7fe9a to 786212a2ce0d (2 revisions) (flutter/flutter#188898) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 0fc8ba72e802 to 0c4faca350cc (2 revisions) (flutter/flutter#188886) 2026-07-01 robert.ancell@canonical.com Hide draft PRs from the triage list (flutter/flutter#188885) 2026-07-01 47866232+chunhtai@users.noreply.github.com Stricten isSemantics and matchesSemantics children mismatch check (flutter/flutter#188827) 2026-07-01 jesswon@google.com [AGP 9] Support Enabling Built-in Kotlin (flutter/flutter#188543) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from d19e557ac317 to 0fc8ba72e802 (4 revisions) (flutter/flutter#188879) 2026-07-01 bkonyi@google.com [ci] Increase test timeout for Mac_x64 build_tests shards (flutter/flutter#188804) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from bd4ae38ca3bb to d19e557ac317 (1 revision) (flutter/flutter#188865) 2026-07-01 engine-flutter-autoroll@skia.org Roll Dart SDK from 26d723eb89af to e47361c7fe9a (5 revisions) (flutter/flutter#188864) 2026-07-01 katelovett@google.com Update triage links for material_ui and cupertino_ui --> Design triage (flutter/flutter#188567) 2026-07-01 flar@google.com [Impeller] Share a single ContextGLES among all PlaygroundImplGLES (flutter/flutter#188080) 2026-07-01 homobonus-luca@hotmail.it Use null-aware elements in dev/devicelab/lib/integration_tests.dart (flutter/flutter#187852) 2026-07-01 engine-flutter-autoroll@skia.org Roll Packages from 274ed3e to e742106 (18 revisions) (flutter/flutter#188863) 2026-07-01 116356835+AbdeMohlbi@users.noreply.github.com Add android 17 to embedding (flutter/flutter#187965) 2026-07-01 47866232+chunhtai@users.noreply.github.com Adds semantics role check to isSemantics and matchesSemantics (flutter/flutter#188825) 2026-07-01 rmacnak@google.com Roll Dart SDK from e1bdb9ce3327 to 26d723eb89af (3 revisions) (flutter/flutter#188795) 2026-07-01 zhongliu88889@gmail.com [web] Apply autocapitalize to text editing elements (flutter/flutter#188351) 2026-07-01 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from RymJjIj7dd5vQ3Cnh... to I2h2eXk06RrA3pIG2... (flutter/flutter#188852) 2026-07-01 bdero@google.com [Impeller] Compute dispatch takes 3D workgroup counts and honors the shader local_size (flutter/flutter#188601) 2026-07-01 codedoctor@linwood.dev Improve stylus support on linux (flutter/flutter#186831) 2026-07-01 matt.boetger@gmail.com Resolve issue Catch am start failures with 'Error type' and prevent hang (flutter/flutter#187196) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from ef178c9898af to bd4ae38ca3bb (3 revisions) (flutter/flutter#188834) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 3ac99be47229 to ef178c9898af (3 revisions) (flutter/flutter#188831) 2026-07-01 31859944+LongCatIsLooong@users.noreply.github.com Add a macosArm64Only feature flag (flutter/flutter#188598) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 15302f1625b2 to 3ac99be47229 (1 revision) (flutter/flutter#188819) 2026-07-01 bkonyi@google.com [flutter_tools] Track asset transformer dependencies for hot reload (Reland #187947) (flutter/flutter#188808) 2026-06-30 737941+loic-sharma@users.noreply.github.com Add TapRegion samples (flutter/flutter#188685) 2026-06-30 31859944+LongCatIsLooong@users.noreply.github.com Print a warning in `flutter doctor` when running on Intel Macs (flutter/flutter#188760) 2026-06-30 zhongliu88889@gmail.com [framework] Keep scrollable semantics role stable (flutter/flutter#187963) 2026-06-30 1961493+harryterkelsen@users.noreply.github.com feat(skills): Add shepherd-prs skill for managing approved external contributor PRs (flutter/flutter#188534) 2026-06-30 engine-flutter-autoroll@skia.org Roll Skia from 71947c4110b0 to 15302f1625b2 (17 revisions) (flutter/flutter#188815) 2026-06-30 bkonyi@google.com [Tool] Run re-entrant upgrade in original CWD (flutter/flutter#188794) ...

…lutter#12135) Manual roll Flutter from ca9f874f5284 to 6995038d96ef (44 revisions) Manual roll requested by stuartmorgan@google.com flutter/flutter@ca9f874...6995038 2026-07-03 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from sx_eN0J_f2BV6jqjW... to Jr08vyeibMSv3Oxst... (flutter/flutter#188946) 2026-07-03 engine-flutter-autoroll@skia.org Roll Packages from 420e135 to 2fbe873 (1 revision) (flutter/flutter#188945) 2026-07-03 engine-flutter-autoroll@skia.org Roll Dart SDK from 786212a2ce0d to 1f9a08ce0638 (4 revisions) (flutter/flutter#188944) 2026-07-03 engine-flutter-autoroll@skia.org Roll Skia from 5358ab75b840 to 919956953af6 (7 revisions) (flutter/flutter#188943) 2026-07-02 j.ihlas@betclicgroup.com [Windows] Keep regular windows in place when another is activated (flutter/flutter#188016) 2026-07-02 okorohelijah@google.com [flutter_tools] Provide guided message when iOS/macOS build fails due to low minimum version (flutter/flutter#188812) 2026-07-02 bdero@google.com [Flutter GPU] Load a ShaderLibrary from shader bundle bytes (flutter/flutter#188596) 2026-07-02 dacoharkes@google.com [tool] Enable record_use experiment by default on all channels (flutter/flutter#188887) 2026-07-02 engine-flutter-autoroll@skia.org Roll Packages from e742106 to 420e135 (13 revisions) (flutter/flutter#188916) 2026-07-02 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from I2h2eXk06RrA3pIG2... to sx_eN0J_f2BV6jqjW... (flutter/flutter#188915) 2026-07-02 256906086+mvincentong@users.noreply.github.com Clarify layout callback debug flag docs (flutter/flutter#186879) 2026-07-02 engine-flutter-autoroll@skia.org Roll Skia from 0c4faca350cc to 5358ab75b840 (2 revisions) (flutter/flutter#188899) 2026-07-02 engine-flutter-autoroll@skia.org Roll Dart SDK from e47361c7fe9a to 786212a2ce0d (2 revisions) (flutter/flutter#188898) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 0fc8ba72e802 to 0c4faca350cc (2 revisions) (flutter/flutter#188886) 2026-07-01 robert.ancell@canonical.com Hide draft PRs from the triage list (flutter/flutter#188885) 2026-07-01 47866232+chunhtai@users.noreply.github.com Stricten isSemantics and matchesSemantics children mismatch check (flutter/flutter#188827) 2026-07-01 jesswon@google.com [AGP 9] Support Enabling Built-in Kotlin (flutter/flutter#188543) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from d19e557ac317 to 0fc8ba72e802 (4 revisions) (flutter/flutter#188879) 2026-07-01 bkonyi@google.com [ci] Increase test timeout for Mac_x64 build_tests shards (flutter/flutter#188804) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from bd4ae38ca3bb to d19e557ac317 (1 revision) (flutter/flutter#188865) 2026-07-01 engine-flutter-autoroll@skia.org Roll Dart SDK from 26d723eb89af to e47361c7fe9a (5 revisions) (flutter/flutter#188864) 2026-07-01 katelovett@google.com Update triage links for material_ui and cupertino_ui --> Design triage (flutter/flutter#188567) 2026-07-01 flar@google.com [Impeller] Share a single ContextGLES among all PlaygroundImplGLES (flutter/flutter#188080) 2026-07-01 homobonus-luca@hotmail.it Use null-aware elements in dev/devicelab/lib/integration_tests.dart (flutter/flutter#187852) 2026-07-01 engine-flutter-autoroll@skia.org Roll Packages from 274ed3e to e742106 (18 revisions) (flutter/flutter#188863) 2026-07-01 116356835+AbdeMohlbi@users.noreply.github.com Add android 17 to embedding (flutter/flutter#187965) 2026-07-01 47866232+chunhtai@users.noreply.github.com Adds semantics role check to isSemantics and matchesSemantics (flutter/flutter#188825) 2026-07-01 rmacnak@google.com Roll Dart SDK from e1bdb9ce3327 to 26d723eb89af (3 revisions) (flutter/flutter#188795) 2026-07-01 zhongliu88889@gmail.com [web] Apply autocapitalize to text editing elements (flutter/flutter#188351) 2026-07-01 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from RymJjIj7dd5vQ3Cnh... to I2h2eXk06RrA3pIG2... (flutter/flutter#188852) 2026-07-01 bdero@google.com [Impeller] Compute dispatch takes 3D workgroup counts and honors the shader local_size (flutter/flutter#188601) 2026-07-01 codedoctor@linwood.dev Improve stylus support on linux (flutter/flutter#186831) 2026-07-01 matt.boetger@gmail.com Resolve issue Catch am start failures with 'Error type' and prevent hang (flutter/flutter#187196) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from ef178c9898af to bd4ae38ca3bb (3 revisions) (flutter/flutter#188834) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 3ac99be47229 to ef178c9898af (3 revisions) (flutter/flutter#188831) 2026-07-01 31859944+LongCatIsLooong@users.noreply.github.com Add a macosArm64Only feature flag (flutter/flutter#188598) 2026-07-01 engine-flutter-autoroll@skia.org Roll Skia from 15302f1625b2 to 3ac99be47229 (1 revision) (flutter/flutter#188819) 2026-07-01 bkonyi@google.com [flutter_tools] Track asset transformer dependencies for hot reload (Reland #187947) (flutter/flutter#188808) 2026-06-30 737941+loic-sharma@users.noreply.github.com Add TapRegion samples (flutter/flutter#188685) 2026-06-30 31859944+LongCatIsLooong@users.noreply.github.com Print a warning in `flutter doctor` when running on Intel Macs (flutter/flutter#188760) 2026-06-30 zhongliu88889@gmail.com [framework] Keep scrollable semantics role stable (flutter/flutter#187963) 2026-06-30 1961493+harryterkelsen@users.noreply.github.com feat(skills): Add shepherd-prs skill for managing approved external contributor PRs (flutter/flutter#188534) 2026-06-30 engine-flutter-autoroll@skia.org Roll Skia from 71947c4110b0 to 15302f1625b2 (17 revisions) (flutter/flutter#188815) 2026-06-30 bkonyi@google.com [Tool] Run re-entrant upgrade in original CWD (flutter/flutter#188794) ...

harryterkelsen requested a review from reidbaker as a code owner June 24, 2026 23:02

flutter-dashboard Bot added the CICD Run CI/CD label Jun 24, 2026

gemini-code-assist Bot reviewed Jun 24, 2026

View reviewed changes

github-actions Bot removed the CICD Run CI/CD label Jun 25, 2026

Piinks added the c: contributor-productivity Team-specific productivity, code health, technical debt. label Jun 29, 2026

reidbaker requested changes Jun 30, 2026

View reviewed changes

harryterkelsen added 11 commits June 30, 2026 10:39

add shepherd_prs skill to automate shepherding pull requests

d72e44b

rename shepherd_prs to shepherd-prs and fix lint warnings

16d92e7

Refactor shepherd.dart to resolve all type lints without ignoring them

b800341

Add Examples section to SKILL.md for repo compliance

18322e9

Move shepherd.dart to scripts/ and update SKILL.md to match agentskil…

274f606

…ls.io spec

refactor(skills): address review comments on shepherd-prs

b9504ff

feat(skills): extend shepherd-prs skill to support shepherding own ap…

c4cb426

…proved PRs

refactor(skills): focus shepherd-prs skill on shepherding own authore…

f8fbdb5

…d open PRs

feat(skills): support dual workflow in shepherd-prs skill for both ow…

713b6a8

…n open PRs and approved third-party PRs

style(skills): add Flutter license header to shepherd.dart

e80517d

docs(skills): address review comments on shepherd-prs documentation

17e931c

harryterkelsen force-pushed the land-shepherd-prs branch from e9e39e8 to 17e931c Compare June 30, 2026 17:43

github-actions Bot removed the c: contributor-productivity Team-specific productivity, code health, technical debt. label Jun 30, 2026

harryterkelsen added c: contributor-productivity Team-specific productivity, code health, technical debt. CICD Run CI/CD labels Jun 30, 2026

style(skills): remove trailing whitespace from SKILL.md

6c81681

github-actions Bot removed the c: contributor-productivity Team-specific productivity, code health, technical debt. label Jun 30, 2026

harryterkelsen requested a review from reidbaker June 30, 2026 17:54

harryterkelsen added the c: contributor-productivity Team-specific productivity, code health, technical debt. label Jun 30, 2026

reidbaker mentioned this pull request Jun 30, 2026

Move add-cicd-label-to-prs skill to reidbaker-agent's skills directory #188527

Closed

reidbaker previously approved these changes Jun 30, 2026

View reviewed changes

Comment thread .agents/skills/shepherd-prs/scripts/README.md

Merged via the queue into flutter:master with commit c13f525 Jun 30, 2026
64 checks passed

flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jun 30, 2026

Conversation

harryterkelsen commented Jun 24, 2026

Description

Skill Usage Examples

Example 1: Retrieving and Summarizing PR Status

Example 2: Running Shepherding on a Specific PR

Pre-launch Checklist

Uh oh!

flutter-dashboard Bot commented Jun 24, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

reidbaker left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

reidbaker Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

harryterkelsen Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

reidbaker Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

harryterkelsen commented Jun 30, 2026

Uh oh!

harryterkelsen commented Jun 30, 2026

Uh oh!

reidbaker left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants