AgentSkillsCN

ai-summary-comment

在GitHub PR上发布或更新自动化进度评论。在完成PR的各个代理阶段后(如预检、测试、门控、修复、报告),这一方法将自动触发“向PR发表评论”、“更新PR进度”、“以结果回复PR”、“发表预检评论”。每个提交都会生成一条聚合的评审评论,且可折叠展示各次提交的详细内容。

SKILL.md
--- frontmatter
name: ai-summary-comment
description: Posts or updates automated progress comments on GitHub PRs. Use after completing any PR agent phase (pre-flight, tests, gate, fix, report). Triggers on 'post comment to PR', 'update PR progress', 'comment on PR with results', 'post pre-flight comment'. Creates single aggregated review comment with collapsible sections per commit.
metadata:
  author: dotnet-maui
  version: "5.0"
compatibility: Requires GitHub CLI (gh) authenticated with access to dotnet/maui repository.

PR Comment Skill

This skill posts automated progress comments to GitHub Pull Requests during the PR review workflow. Comments are self-contained with collapsible Review Session details, providing rich context to maintainers and contributors.

⚠️ Self-Contained Rule: All content in PR comments must be self-contained. Never reference local files like CustomAgentLogsTmp/ - GitHub users cannot access your local filesystem.

✨ Key Features:

  • Single Unified Comment: ONE comment per PR/Issue containing ALL sections (PR Review, Try-Fix, Write-Tests, Verify-Tests)
  • Section-Based Updates: Each script updates only its section, preserving others
  • Duplicate Prevention: Finds existing <!-- AI Summary --> comment and updates it
  • File-Based DryRun Preview: Use -DryRun to preview changes in a local file before posting
  • Auto-Loading State Files: Automatically finds and loads state files from CustomAgentLogsTmp/PRState/
  • Simple Interface: Just provide PR number - script handles everything else

Comment Architecture

Unified AI Summary Comment

Most scripts post to the same single comment identified by <!-- AI Summary -->. Each script updates its own section:

markdown
<!-- AI Summary -->

## 🤖 AI Summary

<!-- SECTION:PR-REVIEW -->
... PR review phases ...
<!-- /SECTION:PR-REVIEW -->

<!-- SECTION:TRY-FIX -->
... try-fix attempts ...
<!-- /SECTION:TRY-FIX -->

<!-- SECTION:WRITE-TESTS -->
... write-tests attempts ...
<!-- /SECTION:WRITE-TESTS -->

<!-- SECTION:VERIFY-TESTS -->
... test verification results ...
<!-- /SECTION:VERIFY-TESTS -->

Behavior:

  • First script to run creates the comment
  • Subsequent scripts find the existing comment and update/add their section
  • Sections are independent - updating one preserves others

Separate PR Finalization Comment

The post-pr-finalize-comment.ps1 script posts a separate comment identified by <!-- PR-FINALIZE-COMMENT -->. This is intentional because:

  • Finalization reviews can happen multiple times (after each commit)
  • Each review is numbered (Review 1, Review 2, etc.)
  • Keeps finalization reviews distinct from automated analysis

Section Scripts

AI Summary Sections (Unified Comment)

SectionScriptLocation
PR-REVIEWpost-ai-summary-comment.ps1.github/skills/ai-summary-comment/scripts/
TRY-FIXpost-try-fix-comment.ps1.github/skills/ai-summary-comment/scripts/
WRITE-TESTSpost-write-tests-comment.ps1.github/skills/ai-summary-comment/scripts/
VERIFY-TESTSpost-verify-tests-comment.ps1.github/skills/ai-summary-comment/scripts/

Separate Comments

CommentScriptMarker
PR Finalizationpost-pr-finalize-comment.ps1<!-- PR-FINALIZE-COMMENT -->

Supported Phases

PhaseDescriptionWhen to PostWhat This Enables Next
pre-flightContext gathering completeAfter documenting issue, files, and discussionTests Phase: Agent can now verify/create test files that reproduce the bug
testsTest analysis completeAfter identifying test files and coverageGate Phase: Agent can run tests to verify they catch the bug
gateTest validation completeAfter running tests and verifying bug reproductionFix Phase: Agent can explore alternative fixes (tests proven to catch bug)
fixSolution comparison completeAfter comparing PR fix with alternativesReport Phase: Agent can finalize recommendation based on fix comparison
reportFinal analysis completeAfter generating comprehensive reviewPR Decision: Maintainers can approve/merge or request changes based on full analysis

Usage

Simplest: Just provide PR number

bash
# Auto-loads CustomAgentLogsTmp/PRState/pr-27246.md
pwsh .github/skills/ai-summary-comment/scripts/post-ai-summary-comment.ps1 -PRNumber 27246

With explicit state file path

bash
# PRNumber auto-extracted from filename (pr-27246.md → 27246)
pwsh .github/skills/ai-summary-comment/scripts/post-ai-summary-comment.ps1 -StateFile CustomAgentLogsTmp/PRState/pr-27246.md

Legacy: Provide content directly

bash
pwsh .github/skills/ai-summary-comment/scripts/post-ai-summary-comment.ps1 -PRNumber 12345 -Content "$(cat CustomAgentLogsTmp/PRState/pr-12345.md)"

Parameters

ParameterRequiredDescriptionExample
PRNumberNo*Pull request number12345
StateFileNo*Path to state file (PRNumber auto-extracted from pr-XXXXX.md naming)CustomAgentLogsTmp/PRState/pr-27246.md
ContentNo*Full state file content (legacy, can be piped via stdin)Content from state file
DryRunNoPreview changes in local file instead of posting to GitHub-DryRun
PreviewFileNoPath to local preview file for DryRun mode (default: CustomAgentLogsTmp/PRState/{PRNumber}/ai-summary-comment-preview.md)-PreviewFile ./preview.md
SkipValidationNoSkip validation checks (not recommended)-SkipValidation

*At least one of PRNumber, StateFile, or Content is required. The script will:

  • If -PRNumber provided: Auto-load CustomAgentLogsTmp/PRState/pr-{PRNumber}.md
  • If -StateFile provided: Load the file and extract PRNumber from pr-XXXXX.md filename
  • If -Content provided: Use content directly (legacy, requires -PRNumber)

DryRun Preview Workflow

Use -DryRun to preview the combined comment before posting to GitHub. Each script updates the same preview file, mirroring how the actual GitHub comment is updated.

bash
# Step 1: Run verify-tests script (creates preview file)
pwsh .github/skills/ai-summary-comment/scripts/post-verify-tests-comment.ps1 -PRNumber 32891 -DryRun

# Step 2: Run try-fix script (updates same preview file)
pwsh .github/skills/ai-summary-comment/scripts/post-try-fix-comment.ps1 -IssueNumber 32891 -DryRun

# Step 3: Review the combined preview
open CustomAgentLogsTmp/PRState/32891/ai-summary-comment-preview.md

# Step 4: Post for real (remove -DryRun)
pwsh .github/skills/ai-summary-comment/scripts/post-verify-tests-comment.ps1 -PRNumber 32891
pwsh .github/skills/ai-summary-comment/scripts/post-try-fix-comment.ps1 -IssueNumber 32891

Key behavior: The preview file exactly matches what will be posted to GitHub. Multiple scripts accumulate their sections in the same file.

Section Ordering

Sections appear in the unified comment in this order (based on which scripts run first):

  1. VERIFY-TESTS - Test verification results
  2. TRY-FIX - Alternative fix exploration attempts
  3. WRITE-TESTS - Test writing attempts
  4. PR-REVIEW - PR review phases

Each section is wrapped with markers like <!-- SECTION:TRY-FIX --> and <!-- /SECTION:TRY-FIX -->.

Cleanup

To reset the preview file for a fresh start:

bash
rm CustomAgentLogsTmp/PRState/{PRNumber}/ai-summary-comment-preview.md

Prerequisites

Scripts require GitHub CLI authentication:

bash
gh auth status  # Verify authentication before running

Comment Format

Comments are formatted with:

  • Phase badge (🔍 Pre-Flight, 🧪 Tests, 🚦 Gate, 🔧 Fix, 📋 Report)
  • Status indicator (✅ Completed, ⚠️ Issues Found)
  • Expandable review sessions (each session is a collapsible section)
  • What's Next (what phase happens next)

Review Session Tracking

When the same PR is reviewed multiple times (e.g., after new commits), the script updates the single aggregated review comment and adds a new expandable section for each commit-based review session.

Example Output

markdown
## 🔍 Pre-Flight: Context Gathering Complete

✅ **Status**: Phase completed successfully

### Summary
- **Issue**: #33356 - CollectionView crash on iOS
- **Platforms Affected**: iOS, MacCatalyst
- **Files Changed**: 2 implementation files, 1 test file
- **Discussion**: 3 key reviewer comments identified

### Key Findings
- Crash occurs when scrolling rapidly with large datasets
- Existing PR adds null check in ItemsViewController
- Test coverage includes iOS device test

### Next Steps
→ **Phase 2: Tests** - Analyzing test files and coverage

---
*Posted by PR Agent @ 2026-01-17 14:23:45 UTC*

Script Files

Try-Fix Comment Script

The post-try-fix-comment.ps1 script updates the <!-- SECTION:TRY-FIX --> section of the unified AI Summary comment. It aggregates all try-fix attempts into collapsible sections. Works for both issues and PRs (GitHub treats PR comments as issue comments).

✨ Auto-Loading from CustomAgentLogsTmp: The script automatically discovers and aggregates ALL attempt directories from CustomAgentLogsTmp/PRState/{IssueNumber}/try-fix/.

Usage

Simplest: Provide attempt directory

powershell
# All parameters auto-loaded from directory structure
pwsh .github/skills/ai-summary-comment/scripts/post-try-fix-comment.ps1 `
    -TryFixDir CustomAgentLogsTmp/PRState/27246/try-fix/attempt-1

Or just provide issue number

powershell
# Auto-discovers and posts latest attempt from CustomAgentLogsTmp/PRState/27246/try-fix/
pwsh .github/skills/ai-summary-comment/scripts/post-try-fix-comment.ps1 -IssueNumber 27246

Legacy: Manual parameters

powershell
pwsh .github/skills/ai-summary-comment/scripts/post-try-fix-comment.ps1 `
    -IssueNumber 19806 `
    -AttemptNumber 1 `
    -Approach "LayoutExtensions Width Constraint" `
    -RootCause "ComputeFrame only constrains width for Fill alignment" `
    -FilesChanged "| File | Changes |`n|------|---------|`n| LayoutExtensions.cs | +17/-3 |" `
    -Status "Compiles" `
    -CodeSnippet "else if (!hasExplicitWidth) { ... }" `
    -Analysis "Core project compiles successfully"

Parameters

ParameterRequiredDescription
TryFixDirNo*Path to try-fix attempt directory (auto-loads all parameters)
IssueNumberNo*Issue or PR number to post comment on
AttemptNumberNo*Attempt number (1, 2, 3, etc.) - auto-detected from TryFixDir
ApproachNo*Brief description of fix approach
RootCauseNoDescription of root cause identified
FilesChangedNo*Markdown table of files changed - auto-generated from diff
StatusNo*"Compiles", "Pass", or "Fail" - loaded from result.txt
CodeSnippetNoCode snippet showing the fix - loaded from fix.diff
AnalysisNoAnalysis of why it worked/failed - loaded from analysis.md
DryRunNoPrint comment instead of posting

*When using -TryFixDir, all marked parameters are auto-loaded from files in the directory.

Expected Directory Structure

code
CustomAgentLogsTmp/PRState/{IssueNumber}/try-fix/
├── attempt-1/
│   ├── approach.md      # Brief description of the approach (required)
│   ├── result.txt       # "Pass", "Fail", or "Compiles" (required)
│   ├── fix.diff         # Git diff of the fix (optional)
│   └── analysis.md      # Detailed analysis (optional)
├── attempt-2/
│   └── ...
└── attempt-3/
    └── ...

Comment Format

markdown
## 🔧 Try-Fix Attempts for Issue #XXXXX

<!-- TRY-FIX-COMMENT -->

<details>
<summary>📊 <strong>Expand Full Details</strong></summary>

**Issue:** [#XXXXX](link)

---

<details>
<summary><strong>🔧 Attempt #1: Approach Name</strong> ✅ Status</summary>
... attempt details ...
</details>

---

*This fix was developed independently.*

</details>

Key Behaviors

  • First attempt creates new comment with <!-- TRY-FIX-COMMENT --> marker
  • Subsequent attempts edit the same comment (no new comments)
  • Outer wrapper shows "📊 Expand Full Details" - keeps PR page clean
  • Each attempt is a nested collapsible section inside the wrapper

Verify-Tests Comment Script

The post-verify-tests-comment.ps1 script updates the <!-- SECTION:VERIFY-TESTS --> section of the unified AI Summary comment. It documents test verification results (whether tests fail without fix and pass with fix).

✨ Auto-Loading from CustomAgentLogsTmp: The script automatically loads verification results from CustomAgentLogsTmp/PRState/{PRNumber}/verify-tests-fail/verification-report.md.

Usage

Simplest: Provide PR number

powershell
# Auto-loads from CustomAgentLogsTmp/PRState/{PRNumber}/verify-tests-fail/
pwsh .github/skills/ai-summary-comment/scripts/post-verify-tests-comment.ps1 -PRNumber 32891

With explicit report file

powershell
pwsh .github/skills/ai-summary-comment/scripts/post-verify-tests-comment.ps1 `
    -PRNumber 32891 `
    -ReportFile CustomAgentLogsTmp/PRState/32891/verify-tests-fail/verification-report.md

Parameters

ParameterRequiredDescription
PRNumberYesPull request number
ReportFileNoPath to verification report (auto-discovered if not provided)
StatusNo"Passed" or "Failed" - auto-detected from report
PlatformNoPlatform tested (ios, android, etc.) - auto-detected from report
ModeNo"FailureOnly" or "FullVerification" - auto-detected from report
DryRunNoPreview changes in local file instead of posting
PreviewFileNoPath to local preview file for DryRun mode

Expected Directory Structure

code
CustomAgentLogsTmp/PRState/{PRNumber}/verify-tests-fail/
├── verification-report.md   # Full verification report (required)
├── verification-log.txt     # Detailed log (optional)
├── test-without-fix.log     # Test output without fix (optional)
└── test-with-fix.log        # Test output with fix (optional)

Write-Tests Comment Script

The post-write-tests-comment.ps1 script updates the <!-- SECTION:WRITE-TESTS --> section of the unified AI Summary comment. It documents test writing attempts for an issue.

✨ Auto-Loading from CustomAgentLogsTmp: The script can automatically load test details from the write-tests output directory structure.

Usage

Simplest: Provide test directory

powershell
# All parameters auto-loaded from directory structure
pwsh .github/skills/ai-summary-comment/scripts/post-write-tests-comment.ps1 `
    -TestDir CustomAgentLogsTmp/PRState/27246/write-tests/attempt-1

Or just provide issue number

powershell
# Auto-discovers and posts latest attempt from CustomAgentLogsTmp/PRState/27246/write-tests/
pwsh .github/skills/ai-summary-comment/scripts/post-write-tests-comment.ps1 -IssueNumber 27246

Legacy: Manual parameters

powershell
pwsh .github/skills/ai-summary-comment/scripts/post-write-tests-comment.ps1 `
    -IssueNumber 33331 `
    -AttemptNumber 1 `
    -TestDescription "Verifies Picker.IsOpen property changes correctly" `
    -HostAppFile "src/Controls/tests/TestCases.HostApp/Issues/Issue33331.cs" `
    -TestFile "src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue33331.cs" `
    -TestMethod "PickerIsOpenPropertyChanges" `
    -Category "Picker" `
    -VerificationStatus "Verified"

Parameters

ParameterRequiredDescription
TestDirNo*Path to write-tests attempt directory (auto-loads all parameters)
IssueNumberNo*Issue or PR number to post comment on
AttemptNumberNo*Attempt number (1, 2, 3, etc.) - auto-detected from TestDir
TestDescriptionNo*Brief description of what the test verifies
HostAppFileNo*Path to the HostApp test page file
TestFileNo*Path to the NUnit test file
TestMethodNo*Name of the test method
CategoryNo*UITestCategories category used
VerificationStatusNo*"Verified", "Failed", or "Unverified" - loaded from result.txt
PlatformsNoPlatforms the test runs on (default: "All")
NotesNoAdditional notes - loaded from notes.md
DryRunNoPrint comment instead of posting

*When using -TestDir, all marked parameters are auto-loaded from files in the directory.

Expected Directory Structure

code
CustomAgentLogsTmp/PRState/{IssueNumber}/write-tests/
├── attempt-1/
│   ├── description.md   # Brief test description (required)
│   ├── test-info.json   # {HostAppFile, TestFile, TestMethod, Category} (required)
│   ├── result.txt       # "Verified", "Pass", "Failed", or "Unverified" (required)
│   └── notes.md         # Additional notes (optional)
├── attempt-2/
│   └── ...
└── attempt-3/
    └── ...

test-info.json Format

json
{
    "HostAppFile": "src/Controls/tests/TestCases.HostApp/Issues/Issue27246.cs",
    "TestFile": "src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue27246.cs",
    "TestMethod": "ScrollToFirstItemWithHeader",
    "Category": "CollectionView"
}

Technical Details

  • Comments identified by HTML marker <!-- AI Summary -->
  • Existing comments are updated (not duplicated) when posting again
  • Review sessions grouped by commit SHA
  • Uses gh api for create/update operations