developer-agent-skills 1.0.0

package/skills/code-review/scripts/collect_review_context.py

@@ -0,0 +1,414 @@
+#!/usr/bin/env python3
+"""Collect deterministic Git context for the code-review Codex skill."""
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+TICKET_RE = re.compile(r"[A-Za-z][A-Za-z0-9]+-\d+")
+VERSION_ONLY_RE = re.compile(r"v\d+", re.IGNORECASE)
+VERSION_SUFFIX_RE = re.compile(r"(?:[-_.]+v\d+)$", re.IGNORECASE)
+
+
+def run_git(repo: str, args: Sequence[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    proc = subprocess.run(
+        ["git", "-C", repo, *args],
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    if check and proc.returncode != 0:
+        cmd = " ".join(["git", "-C", repo, *args])
+        raise RuntimeError(f"Command failed: {cmd}\n{proc.stderr.strip()}")
+    return proc
+
+
+def git_out(repo: str, args: Sequence[str], *, check: bool = True) -> str:
+    return run_git(repo, args, check=check).stdout.strip()
+
+
+def verify_repo(repo: str) -> str:
+    proc = run_git(repo, ["rev-parse", "--show-toplevel"], check=False)
+    if proc.returncode != 0:
+        raise RuntimeError(f"Not a Git repository: {repo}")
+    return proc.stdout.strip()
+
+
+def worktree_dirty(repo: str) -> bool:
+    return bool(git_out(repo, ["status", "--porcelain"], check=False))
+
+
+def try_git_pull(repo: str) -> List[str]:
+    warnings: List[str] = []
+    if worktree_dirty(repo):
+        warnings.append("Skipped git pull because the working tree has uncommitted changes.")
+        return warnings
+
+    proc = run_git(repo, ["pull", "--ff-only"], check=False)
+    if proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout).strip().splitlines()
+        message = detail[-1] if detail else "unknown error"
+        warnings.append(f"git pull --ff-only failed; continuing with local refs. Detail: {message}")
+    return warnings
+
+
+def current_branch(repo: str) -> str:
+    branch = git_out(repo, ["branch", "--show-current"], check=False)
+    if branch:
+        return branch
+    return git_out(repo, ["rev-parse", "--abbrev-ref", "HEAD"])
+
+
+def strip_version_suffix(value: str) -> str:
+    cleaned = value
+    while True:
+        next_value = VERSION_SUFFIX_RE.sub("", cleaned)
+        if next_value == cleaned:
+            return cleaned
+        cleaned = next_value
+
+
+def derive_ticket_prefix(branch: str) -> str:
+    segments = [segment for segment in re.split(r"/+", branch.strip()) if segment]
+    usable = [segment for segment in segments if not VERSION_ONLY_RE.fullmatch(segment)] or segments or [branch]
+
+    for segment in reversed(usable):
+        cleaned = strip_version_suffix(segment)
+        match = TICKET_RE.search(cleaned)
+        if match:
+            return match.group(0)
+
+    return strip_version_suffix(usable[-1]).strip()
+
+
+def ref_exists(repo: str, ref: str) -> bool:
+    proc = run_git(repo, ["rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}"], check=False)
+    return proc.returncode == 0
+
+
+def remote_names(repo: str) -> List[str]:
+    out = git_out(repo, ["remote"], check=False)
+    return [line.strip() for line in out.splitlines() if line.strip()]
+
+
+def strip_ref_namespace(repo: str, ref: str) -> str:
+    clean = ref.strip()
+    for prefix in ("refs/remotes/", "refs/heads/"):
+        if clean.startswith(prefix):
+            clean = clean[len(prefix) :]
+    for remote in sorted(remote_names(repo), key=len, reverse=True):
+        if clean.startswith(remote + "/"):
+            return clean[len(remote) + 1 :]
+    return clean
+
+
+def same_branch_ref(repo: str, ref: str, branch: str) -> bool:
+    return strip_ref_namespace(repo, ref) == strip_ref_namespace(repo, branch)
+
+
+def detect_base_ref(repo: str, requested_base: Optional[str], branch: str) -> Tuple[Optional[str], List[str]]:
+    warnings: List[str] = []
+    if requested_base:
+        if not ref_exists(repo, requested_base):
+            raise RuntimeError(f"Base ref does not exist or is not a commit: {requested_base}")
+        return requested_base, warnings
+
+    upstream = git_out(repo, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], check=False)
+    if upstream and not same_branch_ref(repo, upstream, branch):
+        return upstream, warnings
+    if upstream:
+        warnings.append(f"Upstream {upstream} is the same branch; using a target base branch instead.")
+
+    for candidate in ("origin/main", "origin/master", "origin/develop", "main", "master", "develop"):
+        if ref_exists(repo, candidate):
+            if upstream:
+                warnings.append(f"Using {candidate} as base.")
+            else:
+                warnings.append(f"No upstream configured; using {candidate} as base.")
+            return candidate, warnings
+
+    warnings.append("No upstream/base branch found; commit selection may be incomplete. Pass --base or --commit.")
+    return None, warnings
+
+
+def merge_base(repo: str, base_ref: str) -> str:
+    return git_out(repo, ["merge-base", "HEAD", base_ref])
+
+
+def rev_list(repo: str, *spec_args: str) -> List[str]:
+    out = git_out(repo, ["rev-list", "--reverse", *spec_args], check=False)
+    return [line.strip() for line in out.splitlines() if line.strip()]
+
+
+def expand_commit_spec(repo: str, spec: str) -> List[str]:
+    if ".." in spec:
+        commits = rev_list(repo, spec)
+        if not commits:
+            raise RuntimeError(f"Range produced no commits: {spec}")
+        return commits
+
+    sha = git_out(repo, ["rev-parse", "--verify", f"{spec}^{{commit}}"], check=False)
+    if not sha:
+        raise RuntimeError(f"Commit/ref does not exist: {spec}")
+    return [sha]
+
+
+def dedupe_preserve_order(values: Iterable[str]) -> List[str]:
+    seen = set()
+    result = []
+    for value in values:
+        if value not in seen:
+            seen.add(value)
+            result.append(value)
+    return result
+
+
+def parse_selection(selection: Optional[str], total: int) -> List[int]:
+    if total == 0:
+        return []
+    if not selection or selection.strip().lower() == "all":
+        return list(range(total))
+
+    selected: List[int] = []
+    for raw_part in selection.split(","):
+        part = raw_part.strip()
+        if not part:
+            continue
+        if part.lower() == "all":
+            return list(range(total))
+        if "-" in part:
+            start_text, end_text = part.split("-", 1)
+            if not start_text.strip().isdigit() or not end_text.strip().isdigit():
+                raise RuntimeError(f"Invalid selection range: {part}")
+            start = int(start_text)
+            end = int(end_text)
+            if start > end:
+                start, end = end, start
+            selected.extend(range(start - 1, end))
+        else:
+            if not part.isdigit():
+                raise RuntimeError(f"Invalid selection item: {part}")
+            selected.append(int(part) - 1)
+
+    selected = dedupe_preserve_order(selected)
+    invalid = [index + 1 for index in selected if index < 0 or index >= total]
+    if invalid:
+        raise RuntimeError(f"Selection index out of range for {total} commits: {invalid}")
+    return selected
+
+
+def commit_meta(repo: str, sha: str) -> dict:
+    fmt = "%H%x00%h%x00%an%x00%ad%x00%s"
+    raw = git_out(repo, ["log", "-1", f"--format={fmt}", "--date=iso-strict", sha])
+    full, short, author, date, subject = raw.split("\x00", 4)
+    return {
+        "sha": full,
+        "short": short,
+        "author": author,
+        "date": date,
+        "subject": subject,
+    }
+
+
+def changed_files_for_commit(repo: str, sha: str) -> List[str]:
+    out = git_out(repo, ["diff-tree", "--no-commit-id", "--name-status", "-r", sha], check=False)
+    return [line for line in out.splitlines() if line.strip()]
+
+
+def collect_changed_files(repo: str, commits: Sequence[str]) -> List[str]:
+    files: List[str] = []
+    for sha in commits:
+        files.extend(changed_files_for_commit(repo, sha))
+    return dedupe_preserve_order(files)
+
+
+def git_show(repo: str, sha: str) -> str:
+    return git_out(
+        repo,
+        [
+            "show",
+            "--format=fuller",
+            "--stat",
+            "--patch",
+            "--find-renames",
+            "--find-copies",
+            "--no-ext-diff",
+            "--no-color",
+            sha,
+        ],
+    )
+
+
+def markdown_table(rows: Sequence[dict]) -> str:
+    lines = ["| # | SHA | Date | Author | Subject |", "|---:|---|---|---|---|"]
+    for idx, meta in enumerate(rows, 1):
+        subject = meta["subject"].replace("|", "\\|")
+        author = meta["author"].replace("|", "\\|")
+        lines.append(f"| {idx} | `{meta['short']}` | {meta['date']} | {author} | {subject} |")
+    return "\n".join(lines)
+
+
+def build_context(repo: str, args: argparse.Namespace) -> Tuple[str, int]:
+    repo_root = verify_repo(repo)
+    warnings: List[str] = []
+    if not args.no_pull:
+        warnings.extend(try_git_pull(repo_root))
+    branch = current_branch(repo_root)
+    mode = "branch ticket-prefix filter"
+    base_ref = None
+    base_sha = None
+    ticket_prefix = None
+    range_spec = None
+
+    explicit_specs = []
+    explicit_specs.extend(args.commit or [])
+    explicit_specs.extend(args.range or [])
+
+    if explicit_specs:
+        mode = "explicit commit/range"
+        commits = dedupe_preserve_order(
+            sha for spec in explicit_specs for sha in expand_commit_spec(repo_root, spec)
+        )
+    else:
+        ticket_prefix = derive_ticket_prefix(branch)
+        if not ticket_prefix:
+            raise RuntimeError(f"Could not derive a ticket prefix from branch: {branch}")
+        base_ref, base_warnings = detect_base_ref(repo_root, args.base, branch)
+        warnings.extend(base_warnings)
+        if base_ref:
+            base_sha = merge_base(repo_root, base_ref)
+            range_spec = f"{base_sha}..HEAD"
+            branch_commits = rev_list(repo_root, range_spec)
+        else:
+            branch_commits = rev_list(repo_root, f"--max-count={args.max_commits}", "HEAD")
+            branch_commits = list(reversed(branch_commits))
+
+        prefix_lower = ticket_prefix.lower()
+        commits = []
+        for sha in branch_commits:
+            meta = commit_meta(repo_root, sha)
+            if meta["subject"].lower().startswith(prefix_lower):
+                commits.append(sha)
+
+        if not commits:
+            warnings.append(
+                f"No commits in the branch range have a subject starting with derived ticket prefix '{ticket_prefix}'."
+            )
+
+    if len(commits) > args.max_commits:
+        warnings.append(f"Truncated commit list from {len(commits)} to --max-commits={args.max_commits}.")
+        commits = commits[-args.max_commits :]
+
+    filtered_commit_count = len(commits)
+    selected_indexes = parse_selection(args.select, filtered_commit_count)
+    commits = [commits[index] for index in selected_indexes]
+
+    metadata = [commit_meta(repo_root, sha) for sha in commits]
+    changed_files = collect_changed_files(repo_root, commits)
+
+    lines: List[str] = []
+    lines.append("# Code Review Context")
+    lines.append("")
+    lines.append("## Target")
+    lines.append(f"- Repository: `{repo_root}`")
+    lines.append(f"- Mode: {mode}")
+    lines.append(f"- Branch: `{branch}`")
+    lines.append(f"- Base ref: `{base_ref or 'n/a'}`")
+    lines.append(f"- Base SHA: `{base_sha or 'n/a'}`")
+    lines.append(f"- Range: `{range_spec or ', '.join(explicit_specs) or 'n/a'}`")
+    lines.append(f"- Ticket prefix: `{ticket_prefix or 'n/a'}`")
+    lines.append(f"- Selection: `{args.select or 'all'}`")
+    lines.append(f"- Filtered commit count: {filtered_commit_count}")
+    lines.append(f"- Commit count: {len(commits)}")
+    if warnings:
+        lines.append("")
+        lines.append("## Warnings")
+        for warning in warnings:
+            lines.append(f"- {warning}")
+    lines.append("")
+    lines.append("## Commits")
+    if metadata:
+        lines.append(markdown_table(metadata))
+    else:
+        lines.append("No commits selected.")
+    lines.append("")
+    lines.append("## Changed Files")
+    if changed_files:
+        for item in changed_files:
+            lines.append(f"- `{item}`")
+    else:
+        lines.append("No changed files selected.")
+
+    if args.no_diff or not commits:
+        lines.append("")
+        lines.append("## Diffs")
+        lines.append("Diff output omitted." if args.no_diff else "No diffs selected.")
+        return "\n".join(lines) + "\n", len(commits)
+
+    lines.append("")
+    lines.append("## Diffs")
+    remaining = args.max_diff_chars
+    truncated = False
+    for meta in metadata:
+        if remaining <= 0:
+            truncated = True
+            break
+        diff = git_show(repo_root, meta["sha"])
+        if len(diff) > remaining:
+            diff = diff[:remaining]
+            truncated = True
+        remaining -= len(diff)
+        lines.append("")
+        lines.append(f"### `{meta['short']}` {meta['subject']}")
+        lines.append("```diff")
+        lines.append(diff.rstrip())
+        lines.append("```")
+        if truncated:
+            break
+
+    if truncated:
+        lines.append("")
+        lines.append(f"> Diff output truncated at --max-diff-chars={args.max_diff_chars}. Inspect remaining commits/files directly.")
+
+    return "\n".join(lines) + "\n", len(commits)
+
+
+def parse_args(argv: Sequence[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Collect Git context for a priority-sorted code review report.")
+    parser.add_argument("--repo", default=".", help="Path to the Git repository. Default: current directory.")
+    parser.add_argument("--commit", action="append", help="Commit SHA/ref or range to review. May be passed multiple times.")
+    parser.add_argument("--range", action="append", help="Git revision range to review, e.g. origin/main..HEAD. May be passed multiple times.")
+    parser.add_argument("--base", help="Base branch/ref for branch-mode selection. Default: upstream unless it is the same branch, then origin/main/master/develop.")
+    parser.add_argument("--output", help="Write Markdown context to this path instead of stdout.")
+    parser.add_argument("--max-commits", type=int, default=80, help="Maximum selected commits to include. Default: 80.")
+    parser.add_argument("--max-diff-chars", type=int, default=180000, help="Maximum combined diff characters. Default: 180000.")
+    parser.add_argument("--no-diff", action="store_true", help="Only output metadata and changed file list.")
+    parser.add_argument("--select", help="Select filtered commits by 1-based index list/range, e.g. all, 1, 2-4, 1,3-5. Default: all.")
+    parser.add_argument("--no-pull", action="store_true", help="Skip the default preflight git pull --ff-only attempt.")
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str]) -> int:
+    args = parse_args(argv)
+    try:
+        context, count = build_context(args.repo, args)
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.output:
+        output_path = Path(args.output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(context)
+        print(f"Wrote {output_path} ({count} selected commits)")
+    else:
+        print(context, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/figma/LICENSE.txt

@@ -0,0 +1,2 @@
+Use of these Figma skills and related files ("Materials") is governed by the Figma Developer Terms (available at https://www.figma.com/legal/developer-terms/). By accessing, downloading, or using these Materials — including through automated systems or AI agents — you agree to the Figma Developer Terms.
+These Materials are currently offered as a Beta feature. Figma may modify, suspend, or discontinue them at any time without notice.

package/skills/figma/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: figma
+description: Implement UIs from Figma URLs or design links by opening Figma in Chrome DevTools MCP, inspecting design frames as a developer, capturing screenshots, and extracting layout, colors, and typography directly from the browser view without relying on rate-limited Figma API MCP tools. Trigger when given a Figma link, frame URL, or design-to-code request.
+---
+
+# Figma Browser-Based Inspection (Chrome DevTools MCP Workflow)
+
+Use this skill when given a Figma link or frame URL. Rather than using rate-limited Figma API MCP endpoints, open Figma in the browser via Chrome DevTools MCP, inspect the design as a developer, capture screenshots, and translate the visual spec into clean production code.
+
+---
+
+## Required Workflow (Do Not Skip)
+
+### 1. Open Figma in Browser via Chrome DevTools MCP
+- Take the provided Figma URL (frame, selection, or node link).
+- Open the URL in Chrome using Chrome DevTools MCP (`open_url` / `navigate_to`).
+- Set viewport width to a comfortable desktop resolution (e.g. `1440x900` or `1920x1080` via `resize_page`).
+- Wait until the Figma canvas and UI fully render.
+
+### 2. Capture Visual Reference
+- Take a high-resolution screenshot (`take_screenshot`) of the selected Figma frame or component variant.
+- Save or use this capture as the visual ground truth for implementation.
+
+### 3. Developer Inspection in Figma Browser UI
+- Click into the targeted frame/layer or select the Inspect tab / Dev Mode inside the Figma web app using Chrome DevTools MCP (`click` on canvas or panel buttons).
+- Use `evaluate_script` or browser inspection to extract:
+  - **Layout & Structure**: Container widths, heights, flex/grid layouts, alignment, gap, padding, and margin.
+  - **Color Palette**: Background colors, surface tokens, text colors, border colors, opacity (HEX/RGBA).
+  - **Typography**: Font family, font weight (400, 500, 600, 700), font size, line-height, letter-spacing.
+  - **Effects**: Box shadows, border-radius, border widths, backdrop blurs.
+
+### 4. Translate Design to Code
+- Translate the visual specifications into project conventions:
+  - Map colors to the project's existing color tokens or CSS variables.
+  - Map layout and typography to the project's design system or utility framework (e.g. Tailwind / CSS modules).
+  - Reuse existing UI components (buttons, input fields, badges, icons, modals) rather than duplicating custom markup.
+  - If SVG icons or image assets are visible in the design, extract SVG markup or use appropriate project icons.
+
+### 5. Validate Visual Parity
+- Run the local app dev server.
+- Open the built page in Chrome DevTools MCP alongside the captured Figma screenshot.
+- Verify visual parity (alignment, spacing, typography, colors) before marking complete.
+
+---
+
+## Operating Guidelines
+
+- **No API Quota Limits**: Do NOT call external Figma REST API or rate-limited Figma MCP servers. All inspection is done directly inside the browser using Chrome DevTools MCP.
+- **Visual Fidelity**: Prioritize structural accuracy and component reuse.
+- **Design System First**: Prefer project design system tokens and theme variables over raw hardcoded inline styles whenever project tokens match the design.

package/skills/figma/agents/openai.yaml

@@ -0,0 +1,14 @@
+interface:
+  display_name: "Figma"
+  short_description: "Use Figma MCP for design-to-code work"
+  icon_small: "./assets/figma-small.svg"
+  icon_large: "./assets/figma.png"
+  default_prompt: "Use $figma to inspect the target design and translate it into implementable UI decisions."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "figma"
+      description: "Figma MCP server"
+      transport: "streamable_http"
+      url: "https://mcp.figma.com/mcp"

package/skills/figma/assets/figma-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="#000" fill-rule="evenodd" d="M4.994 5.986a2.014 2.014 0 1 0 0 4.028h2.069V5.986H4.994Zm5.063-.98h.055a2.014 2.014 0 1 0 0-4.026h-2.07v4.027h2.015Zm1.697.49A2.994 2.994 0 0 0 10.112 0H4.994a2.994 2.994 0 0 0-1.642 5.498A2.99 2.99 0 0 0 2 8a2.99 2.99 0 0 0 1.352 2.503A2.99 2.99 0 0 0 2 13.007C2 14.663 3.358 16 5.008 16c1.665 0 3.035-1.349 3.035-3.02v-2.765a2.984 2.984 0 0 0 2.014.778h.055a2.994 2.994 0 0 0 1.642-5.496Zm-1.642.49h-.055a2.014 2.014 0 1 0 0 4.028h.055a2.014 2.014 0 1 0 0-4.028Zm-7.132 7.02c0-1.111.902-2.013 2.014-2.013h2.069v1.987c0 1.123-.924 2.04-2.055 2.04a2.026 2.026 0 0 1-2.028-2.013Zm4.083-8H4.994a2.014 2.014 0 1 1 0-4.026h2.069v4.027Z" clip-rule="evenodd"/>
+</svg>

package/skills/figma/assets/icon.svg

@@ -0,0 +1,28 @@
+<svg
+  width="400"
+  height="400"
+  viewBox="0 0 400 400"
+  fill="none"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <path
+    d="M97.5 302.5C97.5 274.195 120.445 251.25 148.75 251.25H200V302.5C200 330.805 177.055 353.75 148.75 353.75C120.445 353.75 97.5 330.805 97.5 302.5Z"
+    fill="#0ACF83"
+  />
+  <path
+    d="M200 200C200 171.696 222.945 148.75 251.25 148.75C279.554 148.75 302.5 171.695 302.5 200C302.5 228.305 279.554 251.25 251.25 251.25C222.945 251.25 200 228.304 200 200Z"
+    fill="#1ABCFE"
+  />
+  <path
+    d="M97.5 200C97.5 228.305 120.445 251.25 148.75 251.25H200V148.75H148.75C120.445 148.75 97.5 171.695 97.5 200Z"
+    fill="#A259FF"
+  />
+  <path
+    d="M200 46.25V148.75H251.25C279.555 148.75 302.5 125.805 302.5 97.5C302.5 69.1954 279.555 46.25 251.25 46.25H200Z"
+    fill="#FF7262"
+  />
+  <path
+    d="M97.5 97.5C97.5 125.805 120.445 148.75 148.75 148.75H200V46.25L148.75 46.25C120.445 46.25 97.5 69.1954 97.5 97.5Z"
+    fill="#F24E1E"
+  />
+</svg>

package/skills/figma/references/figma-browser-inspection.md

@@ -0,0 +1,24 @@
+# Figma Browser Inspection Guide (Chrome DevTools MCP)
+
+Guide for inspecting Figma designs directly in Chrome DevTools MCP without using rate-limited API keys.
+
+## Browser Navigation Steps
+
+1. **Opening Figma Links**:
+   Use Chrome DevTools MCP `open_url` with the exact Figma frame URL.
+
+2. **Inspecting Canvas & Frames**:
+   - Use `resize_page` to set viewport width (e.g. `1440x900`).
+   - Use `take_screenshot` to capture the visual representation of the target node.
+   - Click on the Inspect panel in Figma to view CSS/properties.
+
+3. **Extracting CSS Specifications**:
+   - **Backgrounds & Surface**: Note HEX / RGBA values.
+   - **Border Radius**: Note border-radius values (`4px`, `8px`, `12px`, `9999px`).
+   - **Shadows**: Note box-shadow values (`offset-x`, `offset-y`, `blur`, `spread`, `color`).
+   - **Flex/Grid**: Note direction, justify-content, align-items, and gap.
+
+4. **Translating to Code**:
+   - Map colors to project design system variables (e.g., `--color-primary`, `bg-slate-900`).
+   - Map font sizes and weights to project typography scale.
+   - Reuse existing component library components (e.g., `<Button>`, `<Card>`, `<Input>`).

package/skills/git-branch-report/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: git-branch-report
+description: Create an on-demand Markdown report for a requested Git branch compared with a base branch. Use when asked for a branch report, branch change summary, diff summary from base, feature branch documentation, or to add a docs file describing what changed in one branch.
+---
+
+# Branch Change Report
+
+Use this skill when the user asks for a change report for a specific Git branch.
+
+## Core Rules
+
+- Generate reports only for the branch the user requested.
+- Default base branch is `origin/main` unless the user specifies another base.
+- Do not bulk-generate reports for every branch.
+- Write reports to `docs/branch-change-reports/<safe-branch-name>.md` by default.
+- Keep the report readable; do not include full patch output unless explicitly requested.
+- The report describes committed differences between base and branch. Mention uncommitted changes only if the user asks for current worktree state.
+
+## Recommended Workflow
+
+1. Resolve inputs.
+   - Confirm the requested branch name from the user prompt.
+   - Use `origin/main` as the default base.
+   - If the branch does not resolve locally, try `origin/<branch>`.
+
+2. Generate the report.
+   - From the repo root (or skill directory), run:
+     `python3 scripts/generate_branch_report.py --branch <branch>`
+   - Use `--base <base>` only when the user requested a different base.
+   - Use `--output-dir <path>` only when the user requested a different output folder.
+
+3. Review the output.
+   - Ensure the generated Markdown includes branch/base metadata, ahead/behind counts, unique commits, changed files, diffstat, impact summary, and testing notes.
+   - If the helper could not infer enough context, add concise human-readable notes after inspecting relevant changed files.
+
+4. Verify.
+   - Run `git diff -- docs/branch-change-reports`.
+   - Report the generated file path and any verification gaps.
+
+## Report Quality
+
+- Group changed files by status and impact area.
+- Use commit messages and paths to infer likely product or technical impact.
+- Call out test files touched.
+- If no tests were touched or run, say that explicitly.
+- Avoid claiming behavior that cannot be inferred from commits or source changes.

package/skills/git-branch-report/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Branch Change Report"
+  short_description: "Create branch reports from Git diffs"
+  default_prompt: "Use $branch-change-report to generate a Markdown change report for the requested branch against origin/main."
+
+policy:
+  allow_implicit_invocation: true