chore(tools): add development and release skills

  Three AI agent skills were previously local-only and not
  version-controlled, making them unavailable to other contributors.

  - Add tools/skills/ with generate_commit_message, pin_upstream_images
    (renamed from tag_release_images), and prepare_release (renamed
    from bump-version) including reference docs and scripts
  - Add tools/skills/README.md with release workflow overview
  - Document all skills in CONTRIBUTING.md with triggers, descriptions,
    and instructions for adding new skills

  Skills are now tracked in the repo and shareable across the team.

Author: fernando-villalba

CONTRIBUTING.md

@@ -85,6 +85,7 @@ pkg/
   testutil/         # Shared test infrastructure (envtest, Kind helpers)
 tools/
   observer/         # Standalone cluster health monitoring tool
+  skills/           # AI agent skills for development and release workflows
 ```
 
 ## Making Changes
@@ -131,3 +132,32 @@ fix(drain): prevent fallthrough on topo unavailability
 docs(readme): update backup architecture section
 chore(deps): update internal Go module dependencies
 ```
+
+## AI Agent Skills
+
+This project includes structured AI agent skills under `tools/skills/` and `tools/observer/skills/`. These are prompt-based workflows that teach AI coding agents (e.g., Claude Code) how to perform specific tasks consistently.
+
+### Available Skills
+
+**Operator Development** ([tools/skills/](tools/skills/)):
+
+| Skill | Trigger | Description |
+|:---|:---|:---|
+| `generate_commit_message` | `/generate_commit_message` | Generate semantic Conventional Commits messages from staged changes. |
+| `pin_upstream_images` | `/pin_upstream_images` | Pin multigres container image SHA tags and review upstream code changes. |
+| `prepare_release` | `/prepare_release` | Full release preparation: changelog, version inference, and doc audit. |
+
+**Observer** ([tools/observer/skills/](tools/observer/skills/)):
+
+| Skill | Trigger | Description |
+|:---|:---|:---|
+| `exercise_cluster` | `/exercise_cluster` | Deploy fixtures, run mutation scenarios, validate health. |
+| `diagnose_with_observer` | `/diagnose_with_observer` | Triage observer findings and produce bug reports. |
+
+### Adding a New Skill
+
+1. Create a directory under `tools/skills/<skill_name>/` with a `SKILL.md` file
+2. Use the frontmatter format (`name`, `description`) — see existing skills for examples
+3. Add reference files under `references/` or scripts under `scripts/` as needed
+4. Create a stub in `.agents/skills/<skill_name>/SKILL.md` pointing to the repo location
+5. Update the [tools/skills/README.md](tools/skills/README.md) table

tools/skills/README.md

@@ -0,0 +1,39 @@
+# Operator Development Skills
+
+AI agent skills for operator development workflows. Each skill is a structured prompt that teaches an agent how to perform a specific task with consistency and precision.
+
+## Available Skills
+
+| Skill | Category | Description |
+|-------|----------|-------------|
+| [generate_commit_message](generate_commit_message/SKILL.md) | Development | Generate semantic Conventional Commits messages from staged changes. |
+| [pin_upstream_images](pin_upstream_images/SKILL.md) | Release | Pin multigres container image SHA tags and review upstream code changes between versions. |
+| [prepare_release](prepare_release/SKILL.md) | Release | Full release preparation: changelog generation, version inference, and documentation audit. |
+
+## Release Workflow
+
+The release skills are designed to be used together:
+
+```
+pin_upstream_images                     prepare_release
+───────────────────                     ───────────────
+1. Fetch latest SHA tags               1. Gather commits since last tag
+2. Update image_defaults.go            2. Categorize changes
+3. Review upstream code changes   ──→   3. Update CHANGELOG.md
+4. Cross-reference operator impact      4. Audit all documentation
+5. Present impact analysis              5. Apply doc fixes
+```
+
+**pin_upstream_images** upgrades the multigres container images and reviews what changed upstream. **prepare_release** then prepares the changelog and audits docs for the full release. Both use **generate_commit_message** for their final commit.
+
+## Usage
+
+These skills are loaded automatically by Claude Code when their trigger phrases are used. You can also invoke them directly:
+
+- `/generate_commit_message` -- after staging changes
+- `/pin_upstream_images` -- when upgrading multigres images
+- `/prepare_release` -- when cutting a new operator release
+
+## See Also
+
+- [Observer Skills](../observer/skills/README.md) -- Skills for cluster health diagnostics (exercise_cluster, diagnose_with_observer)

tools/skills/generate_commit_message/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: generate_commit_message
+description: generate semantic git commit messages
+---
+
+# Generate Commit Message Skill
+
+### ROLE
+You are a Senior DevOps Engineer and Lead Maintainer. Your goal is to generate semantically correct, clean, and highly informative git commit messages based on the provided code diffs.
+
+### RULES (STRICT)
+1.  **Format:** Use the Conventional Commits standard: `type(scope): summary`.
+2.  **Sanitization:** NEVER include `cci:` identifiers, absolute file paths, URI schemes, or Markdown links. Use only relative filenames (e.g., `pkg/auth/...`).
+3.  **Length:** Keep the first line under 50 characters if possible, never over 72. Wrap body text at 72 characters.
+4.  **Mood:** Use the imperative mood for the subject line (e.g., "fix: remove handler" NOT "fixed: removed handler").
+
+### CONTENT STRUCTURE
+Construct the commit body using these three specific sections (you do not need to label them, but the content must flow in this order):
+
+1.  **The Change (What):** A bulleted list of specific technical changes (files, functions, logic).
+2.  **The Context (Why):** A brief explanation of the problem, bug, or missing feature that necessitated this change.
+3.  **The Value (Advantage):** What is the benefit? (e.g., "Improves query performance by 20%", "Prevents race condition during shutdown", "Enables 100% test coverage"). If there a bunch of test changes and implementation code, focus on the actual implementation because the test code changes are likely related to that, rather than the main thing! The test work should be a mention at the end in this case.
+
+### OUTPUT TEMPLATE
+```text
+<type>(<scope>): <short summary>
+
+<The Why: 1-2 sentences on the problem context>
+
+<The What: Bullet points of changes>
+- Refactored [Component] to use [Method]
+- Removed [Deprecated Function] in favor of [New Logic]
+
+<The Advantage: 1 sentence on the impact>
+```

tools/skills/pin_upstream_images/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: pin_upstream_images
+description: Pin multigres container image tags in image_defaults.go for operator releases. Compares upstream multigres code changes between the current and new SHA, highlights breaking changes and new features, then updates the tags. Triggered by user requests like "prepare images for release", "pin image tags", "pin upstream images", or "upgrade multigres images".
+---
+
+# Pin Upstream Images
+
+Upgrade multigres container image tags in `api/v1alpha1/image_defaults.go` to the latest SHA tags, with an upstream code review between the old and new versions.
+
+## Workflow
+
+### 1. Fetch Latest SHA Tags
+
+Run the fetch script to get the latest SHA tags:
+
+```bash
+python3 tools/skills/pin_upstream_images/scripts/fetch_latest_tags.py
+```
+
+This outputs `KEY_TAG=sha-XXXXXXX` for each image. The script resolves which `sha-*` tag currently points to the same digest as `main` for each of:
+- `ghcr.io/multigres/multigres` -> used by DefaultMultiAdminImage, DefaultMultiOrchImage, DefaultMultiPoolerImage, DefaultMultiGatewayImage
+- `ghcr.io/multigres/pgctld` -> used by DefaultPostgresImage
+- `ghcr.io/multigres/multiadmin-web` -> used by DefaultMultiAdminWebImage
+
+### 2. Update Image Tags
+
+Immediately update `api/v1alpha1/image_defaults.go` by replacing the old `sha-XXXXXXX` tags with the new ones:
+
+| Constant                   | Image                              | Tag source      |
+|----------------------------|------------------------------------|-----------------|
+| DefaultPostgresImage       | ghcr.io/multigres/pgctld           | PGCTLD_TAG      |
+| DefaultMultiAdminImage     | ghcr.io/multigres/multigres        | MULTIGRES_TAG   |
+| DefaultMultiAdminWebImage  | ghcr.io/multigres/multiadmin-web   | MULTIADMIN_WEB_TAG |
+| DefaultMultiOrchImage      | ghcr.io/multigres/multigres        | MULTIGRES_TAG   |
+| DefaultMultiPoolerImage    | ghcr.io/multigres/multigres        | MULTIGRES_TAG   |
+| DefaultMultiGatewayImage   | ghcr.io/multigres/multigres        | MULTIGRES_TAG   |
+
+Do NOT modify DefaultEtcdImage -- it uses a separate versioned release.
+
+If old and new SHAs are identical for all images, inform the user that images are already up to date and stop.
+
+### 3. Upstream Code Comparison
+
+All multigres images (`multigres`, `pgctld`, `multiadmin-web`) are built from the same monorepo: `https://github.com/multigres/multigres`. Perform the comparison there.
+
+1. Clone or pull the upstream multigres repo to `/tmp/multigres`:
+   ```bash
+   if [ -d /tmp/multigres ]; then
+     cd /tmp/multigres && git fetch --all && git checkout main && git pull
+   else
+     git clone https://github.com/multigres/multigres /tmp/multigres
+   fi
+   ```
+
+2. Identify the unique old and new SHA values from Step 2. Since `multigres/multigres` and `multigres/pgctld` may have different SHA tags, compare each distinct old->new pair. Typically:
+   - **MULTIGRES_TAG** old SHA vs new SHA (covers multiadmin, multiorch, multipooler, multigateway, and pgctld if they share the same SHA)
+   - **MULTIADMIN_WEB_TAG** old SHA vs new SHA (if different from the above)
+
+3. For each distinct old->new SHA pair, run:
+   ```bash
+   cd /tmp/multigres
+   git log --oneline <old-sha>..<new-sha>
+   git diff --stat <old-sha>..<new-sha>
+   ```
+   Then selectively review the full diff for files that look relevant to the operator (e.g., changes to CLI flags, configuration, proto definitions, RPC interfaces, container entrypoints, health checks, pooler behavior, orchestrator logic, gateway behavior, backup/restore, topology management).
+
+4. If the old and new SHAs are the same for an image group, note that no changes occurred and skip the diff.
+
+### 4. Cross-Reference with Operator Code
+
+This is the critical step. Do NOT make hypothetical recommendations. For each upstream change identified in Step 3, **search the operator codebase** to determine concrete impact.
+
+For every potentially impactful upstream change:
+
+1. **Search the operator code** using `grep_search`, `view_file_outline`, and `view_code_item` to find whether the operator references, uses, or depends on the changed upstream construct (proto field, gRPC service, CLI flag, topology record field, behavior, etc.).
+
+2. **Classify each change with evidence:**
+   - **Action required** -- The operator code directly references or depends on something that changed. Cite the exact file and line in the operator. Describe what needs to change and why.
+   - **New feature opportunity** -- The upstream change introduces a capability the operator *could* support but currently does not. Cite what the upstream change adds and confirm the operator has no existing support for it.
+   - **No impact** -- The upstream change does not touch anything the operator interacts with. Confirm this by showing the search came up empty.
+
+3. **Do not speculate.** Every recommendation must be backed by a concrete search result (or confirmed absence) in the operator codebase. No "if the operator does X" phrasing -- either it does or it doesn't.
+
+### 5. Present Results
+
+Present a structured summary to the user:
+
+**Commits between old and new:**
+- List of commit messages (from `git log --oneline`)
+
+**Impact Analysis:**
+For each upstream change, include:
+- What changed upstream (one-liner)
+- Operator files affected (with file paths and line references) or "none found"
+- Verdict: **Action required** / **New feature opportunity** / **No impact**
+- For action-required items: specific description of what needs to change in the operator
+
+### 6. Finalize
+
+1. Display the `image_defaults.go` diff to the user.
+
+2. Suggest a branch name and generate a commit message using the `generate_commit_message` skill:
+   - Branch name: `release/pin-image-tags-YYYY-MM-DD`
+   - The commit message should reference upgrading multigres images and include the old->new SHA transitions

tools/skills/pin_upstream_images/scripts/fetch_latest_tags.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Fetch the latest SHA tag for each multigres GHCR image that shares the 'main' tag.
+
+Uses the GHCR OCI Distribution API. No authentication needed for public packages.
+Runs digest lookups in parallel for speed.
+
+Output: KEY=VALUE pairs, one per line:
+  MULTIGRES_TAG=sha-XXXXXXX
+  PGCTLD_TAG=sha-XXXXXXX
+  MULTIADMIN_WEB_TAG=sha-XXXXXXX
+"""
+
+import json
+import sys
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+REGISTRY = "ghcr.io"
+
+IMAGES = {
+    "MULTIGRES": "multigres/multigres",
+    "PGCTLD": "multigres/pgctld",
+    "MULTIADMIN_WEB": "multigres/multiadmin-web",
+}
+
+ACCEPT = ",".join([
+    "application/vnd.oci.image.index.v1+json",
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+    "application/vnd.docker.distribution.manifest.v2+json",
+])
+
+
+def get_token(image: str) -> str:
+    url = f"https://{REGISTRY}/token?scope=repository:{image}:pull"
+    with urllib.request.urlopen(url) as resp:
+        return json.loads(resp.read())["token"]
+
+
+def get_digest(image: str, token: str, ref: str) -> str:
+    url = f"https://{REGISTRY}/v2/{image}/manifests/{ref}"
+    req = urllib.request.Request(url, method="HEAD", headers={
+        "Authorization": f"Bearer {token}",
+        "Accept": ACCEPT,
+    })
+    with urllib.request.urlopen(req) as resp:
+        return resp.headers.get("Docker-Content-Digest", "")
+
+
+def get_all_tags(image: str, token: str) -> list[str]:
+    url = f"https://{REGISTRY}/v2/{image}/tags/list?n=10000"
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read()).get("tags", [])
+
+
+def find_sha_tag(image: str, token: str, target_digest: str, sha_tags: list[str]) -> str | None:
+    """Find the sha-* tag matching target_digest using parallel lookups."""
+    with ThreadPoolExecutor(max_workers=20) as pool:
+        future_to_tag = {
+            pool.submit(get_digest, image, token, tag): tag
+            for tag in sha_tags
+        }
+        for future in as_completed(future_to_tag):
+            tag = future_to_tag[future]
+            if future.result() == target_digest:
+                return tag
+    return None
+
+
+def main():
+    results = {}
+    errors = []
+
+    for var_name, image in IMAGES.items():
+        token = get_token(image)
+        main_digest = get_digest(image, token, "main")
+        if not main_digest:
+            errors.append(f"Could not resolve digest for {image}:main")
+            continue
+
+        all_tags = get_all_tags(image, token)
+        sha_tags = [t for t in all_tags if t.startswith("sha-")]
+
+        found = find_sha_tag(image, token, main_digest, sha_tags)
+        if not found:
+            errors.append(
+                f"No sha-* tag matching main for {image} "
+                f"(digest={main_digest}, checked {len(sha_tags)} tags)"
+            )
+            continue
+
+        results[var_name] = found
+
+    # Print results in a stable order
+    for var_name in IMAGES:
+        if var_name in results:
+            print(f"{var_name}_TAG={results[var_name]}")
+
+    if errors:
+        for e in errors:
+            print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()