@xiaotianxt/skills 0.1.0

package/skills/gh-fix-ci/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: "gh-fix-ci"
+description: "Use when a user asks to debug or fix failing GitHub PR checks that run in GitHub Actions. Use GitHub MCP tools for PR metadata and patch context, and use `gh` for Actions check and log inspection before implementing any approved fix."
+---
+
+
+# GitHub Actions CI Fix
+
+## Overview
+
+Use this skill when the task is specifically about failing GitHub Actions checks on a pull request. This workflow is hybrid by design:
+
+- Use GitHub MCP tools for PR metadata, changed files, and review context.
+- Use `gh` for GitHub Actions checks and logs because the connector does not expose that workflow end to end.
+- Summarize the root cause first, propose a focused fix plan, and implement only after explicit approval.
+
+Prereq: authenticate with GitHub CLI once, then confirm with `gh auth status`. Repo and workflow scopes are typically required for Actions inspection.
+
+## Inputs
+
+- `repo`: path inside the repo (default `.`)
+- `pr`: PR number or URL (optional; defaults to current branch PR)
+- `gh` authentication for the repo host
+
+## Quick start
+
+- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`
+- Add `--json` if you want machine-friendly output for summarization.
+
+## Workflow
+
+1. Verify gh authentication.
+   - Run `gh auth status` in the repo.
+   - If unauthenticated, ask the user to run `gh auth login` (ensuring repo + workflow scopes) before proceeding.
+2. Resolve the PR.
+   - If the user provides a PR number or URL, use that directly.
+   - Otherwise prefer the current branch PR with `gh pr view --json number,url`.
+   - When repo and PR are known, fetch PR metadata and patch context through GitHub MCP tools.
+3. Inspect failing checks (GitHub Actions only).
+   - Preferred: run the bundled script (handles gh field drift and job-log fallbacks):
+     - `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`
+     - Add `--json` for machine-friendly output.
+   - Manual fallback:
+     - `gh pr checks <pr> --json name,state,bucket,link,startedAt,completedAt,workflow`
+       - If a field is rejected, rerun with the available fields reported by `gh`.
+     - For each failing check, extract the run id from `detailsUrl` and run:
+       - `gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha`
+       - `gh run view <run_id> --log`
+     - If the run log says it is still in progress, fetch job logs directly:
+       - `gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs" > "<path>"`
+4. Scope non-GitHub Actions checks.
+   - If `detailsUrl` is not a GitHub Actions run, label it as external and only report the URL.
+   - Do not attempt Buildkite or other providers; keep the workflow lean.
+5. Summarize failures for the user.
+   - Provide the failing check name, run URL (if any), and a concise log snippet.
+   - Call out missing logs explicitly and do not over-claim certainty.
+6. Propose a focused fix plan and wait for approval.
+   - Keep the plan tied directly to the failing checks and the observed root cause.
+7. Implement after approval.
+   - Apply the approved fix locally.
+   - Run the most relevant local verification available.
+8. Recheck status and summarize residual risk.
+   - Suggest re-running the relevant tests and `gh pr checks`.
+   - Report what is still unverified, what may still be flaky, and whether any failing checks were external and therefore not actionable here.
+
+## Bundled Resources
+
+### scripts/inspect_pr_checks.py
+
+Fetch failing PR checks, pull GitHub Actions logs, and extract a failure snippet. Exits non-zero when failures remain so it can be used in automation.
+
+Usage examples:
+- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "123"`
+- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "https://github.com/org/repo/pull/123" --json`
+- `python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --max-lines 200 --context 40`
+
+## Guardrails
+
+- Do not imply that GitHub MCP can replace `gh` for Actions log retrieval.
+- Treat non-GitHub Actions providers as report-only unless the user explicitly wants a separate investigation path.
+- If the failure is clearly unrelated to the local diff, say so before proposing code changes.

package/skills/gh-fix-ci/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CI Debug"
+  short_description: "Debug failing GitHub Actions checks"
+  icon_small: "./assets/github-small.svg"
+  icon_large: "./assets/github.png"
+  default_prompt: "Use $gh-fix-ci to inspect the failing GitHub Actions checks on this PR, summarize the root cause, and propose the smallest viable fix."

package/skills/gh-fix-ci/assets/github-small.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+  <path fill="currentColor" d="M8 1.3a6.665 6.665 0 0 1 5.413 10.56 6.677 6.677 0 0 1-3.288 2.432c-.333.067-.458-.142-.458-.316 0-.226.008-.942.008-1.834 0-.625-.208-1.025-.45-1.233 1.483-.167 3.042-.734 3.042-3.292a2.58 2.58 0 0 0-.684-1.792c.067-.166.3-.85-.066-1.766 0 0-.559-.184-1.834.683a6.186 6.186 0 0 0-1.666-.225c-.567 0-1.134.075-1.667.225-1.275-.858-1.833-.683-1.833-.683-.367.916-.134 1.6-.067 1.766a2.594 2.594 0 0 0-.683 1.792c0 2.55 1.55 3.125 3.033 3.292-.192.166-.367.458-.425.891-.383.175-1.342.459-1.942-.55-.125-.2-.5-.691-1.025-.683-.558.008-.225.317.009.442.283.158.608.75.683.941.133.376.567 1.092 2.242.784 0 .558.008 1.083.008 1.242 0 .174-.125.374-.458.316a6.662 6.662 0 0 1-4.559-6.325A6.665 6.665 0 0 1 8 1.3Z"/>
+</svg>

package/skills/gh-fix-ci/scripts/inspect_pr_checks.py

@@ -0,0 +1,509 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+from shutil import which
+from typing import Any, Iterable, Sequence
+
+FAILURE_CONCLUSIONS = {
+    "failure",
+    "cancelled",
+    "timed_out",
+    "action_required",
+}
+
+FAILURE_STATES = {
+    "failure",
+    "error",
+    "cancelled",
+    "timed_out",
+    "action_required",
+}
+
+FAILURE_BUCKETS = {"fail"}
+
+FAILURE_MARKERS = (
+    "error",
+    "fail",
+    "failed",
+    "traceback",
+    "exception",
+    "assert",
+    "panic",
+    "fatal",
+    "timeout",
+    "segmentation fault",
+)
+
+DEFAULT_MAX_LINES = 160
+DEFAULT_CONTEXT_LINES = 30
+PENDING_LOG_MARKERS = (
+    "still in progress",
+    "log will be available when it is complete",
+)
+
+
+class GhResult:
+    def __init__(self, returncode: int, stdout: str, stderr: str):
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+
+
+def run_gh_command(args: Sequence[str], cwd: Path) -> GhResult:
+    process = subprocess.run(
+        ["gh", *args],
+        cwd=cwd,
+        text=True,
+        capture_output=True,
+    )
+    return GhResult(process.returncode, process.stdout, process.stderr)
+
+
+def run_gh_command_raw(args: Sequence[str], cwd: Path) -> tuple[int, bytes, str]:
+    process = subprocess.run(
+        ["gh", *args],
+        cwd=cwd,
+        capture_output=True,
+    )
+    stderr = process.stderr.decode(errors="replace")
+    return process.returncode, process.stdout, stderr
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Inspect failing GitHub PR checks, fetch GitHub Actions logs, and extract a "
+            "failure snippet."
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument("--repo", default=".", help="Path inside the target Git repository.")
+    parser.add_argument(
+        "--pr", default=None, help="PR number or URL (defaults to current branch PR)."
+    )
+    parser.add_argument("--max-lines", type=int, default=DEFAULT_MAX_LINES)
+    parser.add_argument("--context", type=int, default=DEFAULT_CONTEXT_LINES)
+    parser.add_argument("--json", action="store_true", help="Emit JSON instead of text output.")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    repo_root = find_git_root(Path(args.repo))
+    if repo_root is None:
+        print("Error: not inside a Git repository.", file=sys.stderr)
+        return 1
+
+    if not ensure_gh_available(repo_root):
+        return 1
+
+    pr_value = resolve_pr(args.pr, repo_root)
+    if pr_value is None:
+        return 1
+
+    checks = fetch_checks(pr_value, repo_root)
+    if checks is None:
+        return 1
+
+    failing = [c for c in checks if is_failing(c)]
+    if not failing:
+        print(f"PR #{pr_value}: no failing checks detected.")
+        return 0
+
+    results = []
+    for check in failing:
+        results.append(
+            analyze_check(
+                check,
+                repo_root=repo_root,
+                max_lines=max(1, args.max_lines),
+                context=max(1, args.context),
+            )
+        )
+
+    if args.json:
+        print(json.dumps({"pr": pr_value, "results": results}, indent=2))
+    else:
+        render_results(pr_value, results)
+
+    return 1
+
+
+def find_git_root(start: Path) -> Path | None:
+    result = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        cwd=start,
+        text=True,
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        return None
+    return Path(result.stdout.strip())
+
+
+def ensure_gh_available(repo_root: Path) -> bool:
+    if which("gh") is None:
+        print("Error: gh is not installed or not on PATH.", file=sys.stderr)
+        return False
+    result = run_gh_command(["auth", "status"], cwd=repo_root)
+    if result.returncode == 0:
+        return True
+    message = (result.stderr or result.stdout or "").strip()
+    print(message or "Error: gh not authenticated.", file=sys.stderr)
+    return False
+
+
+def resolve_pr(pr_value: str | None, repo_root: Path) -> str | None:
+    if pr_value:
+        return pr_value
+    result = run_gh_command(["pr", "view", "--json", "number"], cwd=repo_root)
+    if result.returncode != 0:
+        message = (result.stderr or result.stdout or "").strip()
+        print(message or "Error: unable to resolve PR.", file=sys.stderr)
+        return None
+    try:
+        data = json.loads(result.stdout or "{}")
+    except json.JSONDecodeError:
+        print("Error: unable to parse PR JSON.", file=sys.stderr)
+        return None
+    number = data.get("number")
+    if not number:
+        print("Error: no PR number found.", file=sys.stderr)
+        return None
+    return str(number)
+
+
+def fetch_checks(pr_value: str, repo_root: Path) -> list[dict[str, Any]] | None:
+    primary_fields = ["name", "state", "conclusion", "detailsUrl", "startedAt", "completedAt"]
+    result = run_gh_command(
+        ["pr", "checks", pr_value, "--json", ",".join(primary_fields)],
+        cwd=repo_root,
+    )
+    if result.returncode != 0:
+        message = "\n".join(filter(None, [result.stderr, result.stdout])).strip()
+        available_fields = parse_available_fields(message)
+        if available_fields:
+            fallback_fields = [
+                "name",
+                "state",
+                "bucket",
+                "link",
+                "startedAt",
+                "completedAt",
+                "workflow",
+            ]
+            selected_fields = [field for field in fallback_fields if field in available_fields]
+            if not selected_fields:
+                print("Error: no usable fields available for gh pr checks.", file=sys.stderr)
+                return None
+            result = run_gh_command(
+                ["pr", "checks", pr_value, "--json", ",".join(selected_fields)],
+                cwd=repo_root,
+            )
+            if result.returncode != 0:
+                message = (result.stderr or result.stdout or "").strip()
+                print(message or "Error: gh pr checks failed.", file=sys.stderr)
+                return None
+        else:
+            print(message or "Error: gh pr checks failed.", file=sys.stderr)
+            return None
+    try:
+        data = json.loads(result.stdout or "[]")
+    except json.JSONDecodeError:
+        print("Error: unable to parse checks JSON.", file=sys.stderr)
+        return None
+    if not isinstance(data, list):
+        print("Error: unexpected checks JSON shape.", file=sys.stderr)
+        return None
+    return data
+
+
+def is_failing(check: dict[str, Any]) -> bool:
+    conclusion = normalize_field(check.get("conclusion"))
+    if conclusion in FAILURE_CONCLUSIONS:
+        return True
+    state = normalize_field(check.get("state") or check.get("status"))
+    if state in FAILURE_STATES:
+        return True
+    bucket = normalize_field(check.get("bucket"))
+    return bucket in FAILURE_BUCKETS
+
+
+def analyze_check(
+    check: dict[str, Any],
+    repo_root: Path,
+    max_lines: int,
+    context: int,
+) -> dict[str, Any]:
+    url = check.get("detailsUrl") or check.get("link") or ""
+    run_id = extract_run_id(url)
+    job_id = extract_job_id(url)
+    base: dict[str, Any] = {
+        "name": check.get("name", ""),
+        "detailsUrl": url,
+        "runId": run_id,
+        "jobId": job_id,
+    }
+
+    if run_id is None:
+        base["status"] = "external"
+        base["note"] = "No GitHub Actions run id detected in detailsUrl."
+        return base
+
+    metadata = fetch_run_metadata(run_id, repo_root)
+    log_text, log_error, log_status = fetch_check_log(
+        run_id=run_id,
+        job_id=job_id,
+        repo_root=repo_root,
+    )
+
+    if log_status == "pending":
+        base["status"] = "log_pending"
+        base["note"] = log_error or "Logs are not available yet."
+        if metadata:
+            base["run"] = metadata
+        return base
+
+    if log_error:
+        base["status"] = "log_unavailable"
+        base["error"] = log_error
+        if metadata:
+            base["run"] = metadata
+        return base
+
+    snippet = extract_failure_snippet(log_text, max_lines=max_lines, context=context)
+    base["status"] = "ok"
+    base["run"] = metadata or {}
+    base["logSnippet"] = snippet
+    base["logTail"] = tail_lines(log_text, max_lines)
+    return base
+
+
+def extract_run_id(url: str) -> str | None:
+    if not url:
+        return None
+    for pattern in (r"/actions/runs/(\d+)", r"/runs/(\d+)"):
+        match = re.search(pattern, url)
+        if match:
+            return match.group(1)
+    return None
+
+
+def extract_job_id(url: str) -> str | None:
+    if not url:
+        return None
+    match = re.search(r"/actions/runs/\d+/job/(\d+)", url)
+    if match:
+        return match.group(1)
+    match = re.search(r"/job/(\d+)", url)
+    if match:
+        return match.group(1)
+    return None
+
+
+def fetch_run_metadata(run_id: str, repo_root: Path) -> dict[str, Any] | None:
+    fields = [
+        "conclusion",
+        "status",
+        "workflowName",
+        "name",
+        "event",
+        "headBranch",
+        "headSha",
+        "url",
+    ]
+    result = run_gh_command(["run", "view", run_id, "--json", ",".join(fields)], cwd=repo_root)
+    if result.returncode != 0:
+        return None
+    try:
+        data = json.loads(result.stdout or "{}")
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    return data
+
+
+def fetch_check_log(
+    run_id: str,
+    job_id: str | None,
+    repo_root: Path,
+) -> tuple[str, str, str]:
+    log_text, log_error = fetch_run_log(run_id, repo_root)
+    if not log_error:
+        return log_text, "", "ok"
+
+    if is_log_pending_message(log_error) and job_id:
+        job_log, job_error = fetch_job_log(job_id, repo_root)
+        if job_log:
+            return job_log, "", "ok"
+        if job_error and is_log_pending_message(job_error):
+            return "", job_error, "pending"
+        if job_error:
+            return "", job_error, "error"
+        return "", log_error, "pending"
+
+    if is_log_pending_message(log_error):
+        return "", log_error, "pending"
+
+    return "", log_error, "error"
+
+
+def fetch_run_log(run_id: str, repo_root: Path) -> tuple[str, str]:
+    result = run_gh_command(["run", "view", run_id, "--log"], cwd=repo_root)
+    if result.returncode != 0:
+        error = (result.stderr or result.stdout or "").strip()
+        return "", error or "gh run view failed"
+    return result.stdout, ""
+
+
+def fetch_job_log(job_id: str, repo_root: Path) -> tuple[str, str]:
+    repo_slug = fetch_repo_slug(repo_root)
+    if not repo_slug:
+        return "", "Error: unable to resolve repository name for job logs."
+    endpoint = f"/repos/{repo_slug}/actions/jobs/{job_id}/logs"
+    returncode, stdout_bytes, stderr = run_gh_command_raw(["api", endpoint], cwd=repo_root)
+    if returncode != 0:
+        message = (stderr or stdout_bytes.decode(errors="replace")).strip()
+        return "", message or "gh api job logs failed"
+    if is_zip_payload(stdout_bytes):
+        return "", "Job logs returned a zip archive; unable to parse."
+    return stdout_bytes.decode(errors="replace"), ""
+
+
+def fetch_repo_slug(repo_root: Path) -> str | None:
+    result = run_gh_command(["repo", "view", "--json", "nameWithOwner"], cwd=repo_root)
+    if result.returncode != 0:
+        return None
+    try:
+        data = json.loads(result.stdout or "{}")
+    except json.JSONDecodeError:
+        return None
+    name_with_owner = data.get("nameWithOwner")
+    if not name_with_owner:
+        return None
+    return str(name_with_owner)
+
+
+def normalize_field(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip().lower()
+
+
+def parse_available_fields(message: str) -> list[str]:
+    if "Available fields:" not in message:
+        return []
+    fields: list[str] = []
+    collecting = False
+    for line in message.splitlines():
+        if "Available fields:" in line:
+            collecting = True
+            continue
+        if not collecting:
+            continue
+        field = line.strip()
+        if not field:
+            continue
+        fields.append(field)
+    return fields
+
+
+def is_log_pending_message(message: str) -> bool:
+    lowered = message.lower()
+    return any(marker in lowered for marker in PENDING_LOG_MARKERS)
+
+
+def is_zip_payload(payload: bytes) -> bool:
+    return payload.startswith(b"PK")
+
+
+def extract_failure_snippet(log_text: str, max_lines: int, context: int) -> str:
+    lines = log_text.splitlines()
+    if not lines:
+        return ""
+
+    marker_index = find_failure_index(lines)
+    if marker_index is None:
+        return "\n".join(lines[-max_lines:])
+
+    start = max(0, marker_index - context)
+    end = min(len(lines), marker_index + context)
+    window = lines[start:end]
+    if len(window) > max_lines:
+        window = window[-max_lines:]
+    return "\n".join(window)
+
+
+def find_failure_index(lines: Sequence[str]) -> int | None:
+    for idx in range(len(lines) - 1, -1, -1):
+        lowered = lines[idx].lower()
+        if any(marker in lowered for marker in FAILURE_MARKERS):
+            return idx
+    return None
+
+
+def tail_lines(text: str, max_lines: int) -> str:
+    if max_lines <= 0:
+        return ""
+    lines = text.splitlines()
+    return "\n".join(lines[-max_lines:])
+
+
+def render_results(pr_number: str, results: Iterable[dict[str, Any]]) -> None:
+    results_list = list(results)
+    print(f"PR #{pr_number}: {len(results_list)} failing checks analyzed.")
+    for result in results_list:
+        print("-" * 60)
+        print(f"Check: {result.get('name', '')}")
+        if result.get("detailsUrl"):
+            print(f"Details: {result['detailsUrl']}")
+        run_id = result.get("runId")
+        if run_id:
+            print(f"Run ID: {run_id}")
+        job_id = result.get("jobId")
+        if job_id:
+            print(f"Job ID: {job_id}")
+        status = result.get("status", "unknown")
+        print(f"Status: {status}")
+
+        run_meta = result.get("run", {})
+        if run_meta:
+            branch = run_meta.get("headBranch", "")
+            sha = (run_meta.get("headSha") or "")[:12]
+            workflow = run_meta.get("workflowName") or run_meta.get("name") or ""
+            conclusion = run_meta.get("conclusion") or run_meta.get("status") or ""
+            print(f"Workflow: {workflow} ({conclusion})")
+            if branch or sha:
+                print(f"Branch/SHA: {branch} {sha}")
+            if run_meta.get("url"):
+                print(f"Run URL: {run_meta['url']}")
+
+        if result.get("note"):
+            print(f"Note: {result['note']}")
+
+        if result.get("error"):
+            print(f"Error fetching logs: {result['error']}")
+            continue
+
+        snippet = result.get("logSnippet") or ""
+        if snippet:
+            print("Failure snippet:")
+            print(indent_block(snippet, prefix="  "))
+        else:
+            print("No snippet available.")
+    print("-" * 60)
+
+
+def indent_block(text: str, prefix: str = "  ") -> str:
+    return "\n".join(f"{prefix}{line}" for line in text.splitlines())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/gh-review-workflow/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: gh-review-workflow
+description: Inspect and address GitHub pull request review state, including latest PR comments, review submissions, unresolved inline threads, actionable review feedback, and post-fix thread resolution. Use when Codex needs to check "latest PR comments", summarize or implement requested PR changes, inspect the current branch PR, or resolve review threads after fixes are pushed.
+---
+
+# GH Review Workflow
+
+Use this skill when the user wants the real review state of a GitHub PR, not just flat issue comments. Prefer GitHub connector/MCP tools for repository and PR metadata. Use the bundled scripts or `gh api graphql` when you need inline review threads, `isResolved`, `isOutdated`, or file and line anchors.
+
+## Workflow
+
+1. Resolve the target PR.
+- If the user provides a PR URL or repo plus PR number, use that directly.
+- If the task is about the current branch PR, run `gh auth status` and then use the bundled `scripts/fetch_review_state.py` with no arguments.
+- If the task is about the latest PR in a repo, first use GitHub metadata tools to list PRs sorted by create time.
+
+2. Inspect metadata and flat comments.
+- Use GitHub connector data for PR title, head/base branches, and top-level PR comments.
+- Do not treat flat PR comments as complete review state.
+
+3. Inspect review threads.
+- Run `python3 ~/.codex/skills/gh-review-workflow/scripts/fetch_review_state.py` for the current branch PR.
+- Or run `python3 ~/.codex/skills/gh-review-workflow/scripts/fetch_review_state.py --owner OWNER --repo REPO --number 123`.
+- Read `review_threads` first. That is the source of truth for inline review comments and resolution state.
+
+4. Summarize actionability.
+- Group duplicate comments by behavior or file instead of answering each line independently.
+- Separate real blockers from style suggestions and "reply only" items.
+- Call out whether a thread is still current or already `isOutdated`.
+
+5. If the user asks to address review feedback.
+- Confirm the intended scope unless the user explicitly says to fix all unresolved actionable threads.
+- Keep each code change traceable to a feedback cluster.
+- If a comment needs explanation rather than code, draft the response instead of forcing a code change.
+- Verify locally before pushing or resolving any thread.
+
+6. After fixes.
+- Verify code locally before pushing.
+- Push the branch.
+- If the user asked to resolve addressed threads, run `python3 ~/.codex/skills/gh-review-workflow/scripts/resolve_review_threads.py THREAD_ID...`.
+- If the user wants to resolve all unresolved threads captured in a saved JSON dump, run `python3 ~/.codex/skills/gh-review-workflow/scripts/resolve_review_threads.py --from-json review_state.json`.
+
+## Interpretation Rules
+
+- `conversation_comments` are top-level PR comments.
+- `reviews` are submitted or draft review objects. `PENDING` means there is a draft review even if no formal review event was submitted yet.
+- `review_threads` hold inline review comments, anchors, and resolution state.
+- `isOutdated: true` means the original diff context moved or changed; decide whether the underlying concern is already addressed before ignoring it.
+- Repeated comments like "can we reuse X?" often map to one design decision. Cluster them.
+
+## Write Safety
+
+- Do not comment on GitHub or resolve review threads unless the user explicitly asked for a write.
+- Do not reject a suggestion vaguely. If keeping the current design, explain the ABI, spec, or ownership reason concretely.
+- For review requests, prioritize behavioral bugs, regressions, and missing validation over cosmetic style changes.
+
+## Resources
+
+- Read [workflow.md](references/workflow.md) for the tool split and response template.
+- Use `scripts/fetch_review_state.py` for thread-aware reads.
+- Use `scripts/resolve_review_threads.py` for post-fix cleanup.

package/skills/gh-review-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GH Review Workflow"
+  short_description: "Inspect and close PR review threads"
+  default_prompt: "Inspect the latest PR review comments, summarize what is actionable, and help resolve the threads after fixes are pushed."