Cross-Platform Agent Skills: Writing Universal SKILL.md for Antigravity, OpenCode & Claude Code

┌──────────────────────────────────────────────────────────────┐
│                    Universal Skill Folder                    │
│                                                              │
│   my-skill/                                                  │
│   ├── SKILL.md        (Standard YAML Frontmatter + Markdown) │
│   ├── scripts/        (Portable Python / POSIX Sh)           │
│   ├── references/     (Static Markdown / Cheat sheets)       │
│   └── templates/      (Jinja / Handlebars / Text templates)  │
└──────────────────────────────┬───────────────────────────────┘
                               │
       ┌───────────────────────┼───────────────────────┐
       ▼                       ▼                       ▼
┌──────────────┐       ┌──────────────┐       ┌────────────────┐
│  Antigravity │       │   OpenCode   │       │  Claude Code   │
│ CLI & Desktop│       │  CLI & Web   │       │   CLI Engine   │
│  (Google AI) │       │ (Open Source)│       │  (Anthropic)   │
└──────────────┘       └──────────────┘       └────────────────┘

1. Active Session Override (--skill / CLI flag)
   └── 2. Project Local (.agents/skills/<name>/)
       └── 3. Workspace Shared (.cursor/ / .github/)
           └── 4. User Global (~/.gemini/... or ~/.claude/...)
               └── 5. Built-in Harness Bundles

[ Tier 1: Catalog ] ──▶ Name + Description loaded at session boot (~50-100 tokens)
                                 │
                                 ▼ (Trigger condition matched by router)
[ Tier 2: Instructions ] ──▶ SKILL.md body loaded into active context (<5,000 tokens)
                                 │
                                 ▼ (Agent determines script / file is needed)
[ Tier 3: Resources ] ──▶ Scripts, templates, and references read on demand

❌ Bad: Non-portable Bashism
#!/usr/bin/env bash
declare -A MAP=( [key]="value" ) # Fails on default macOS bash (v3.2)
source "${0%/*}/helpers.sh"

✅ Good: POSIX-compliant shell wrapper or Python 3 standard library
#!/usr/bin/env python3
# Standard library only: sys, os, subprocess, json, argparse

### Executing Helper Scripts

Run the bundled script using Python 3:

```bash
# Locate the script from the skill directory:
python3 $(find . -path "*/skills/release-notes/scripts/summarize_git.py" | head -n 1) --from-tag "$(git describe --tags --abbrev=0 2>/dev/null || echo '')"
```

import os
import sys

# Compute the skill root directory regardless of current working directory
SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
SKILL_ROOT = os.path.dirname(SCRIPT_DIR)
TEMPLATES_DIR = os.path.join(SKILL_ROOT, "templates")
REFERENCES_DIR = os.path.join(SKILL_ROOT, "references")

---
name: release-notes-generator
description: |
  Generates production changelogs and release notes from Git commit history, PRs, and conventional commit tags.
  Use this skill whenever the user asks to:
  - "create release notes"
  - "generate changelog"
  - "prepare release summary for vX.Y.Z"
  - "summarize changes since last tag"
  Do NOT use for single commit message generation (use standard git commit workflows instead).
---

.agents/skills/release-notes/
├── SKILL.md
├── scripts/
│   └── summarize_git.py
├── templates/
│   └── release_template.md
└── references/
    └── conventional_commits.md

---
name: release-notes
description: |
  Automates the generation of structured, categorized release notes and changelogs from Git commit logs.
  Triggers on requests to "draft release notes", "generate changelog", "summarize commits since last release",
  or "prepare vX.Y.Z release notes". Uses Conventional Commits standards to group breaking changes,
  features, bug fixes, and performance improvements.
---

# Release Notes Generator

This skill extracts git history between two tags or commits, parses conventional commit conventions, and formats production-ready release notes using standard templates.

## Workflow

Follow these steps sequentially to generate release notes:

### Step 1: Inspect Git Repository & Identify Range

Determine the start and end revisions:
1. Find the latest Git tag:
   ```bash
   git describe --tags --abbrev=0 2>/dev/null || echo "INITIAL"

# Locate the script relative to skill paths
python3 $(find . -path "*/skills/release-notes/scripts/summarize_git.py" | head -n 1) --from-tag "$(git describe --tags --abbrev=0 2>/dev/null || echo '')" --to-ref "HEAD"

git log --pretty=format:"%h|%s|%an|%ad" --date=short $(git describe --tags --abbrev=0 2>/dev/null)..HEAD

---

### 3. The Extraction Script (`summarize_git.py`)

Create `.agents/skills/release-notes/scripts/summarize_git.py` using pure Python 3 standard library:

```python
#!/usr/bin/env python3
"""
Universal Git Commit Extractor & Categorizer for Agent Skills.
Requires Python 3.8+ with zero third-party dependencies.
"""

import argparse
import json
import re
import subprocess
import sys


CONVENTIONAL_PATTERN = re.compile(
    r"^(?P<type>feat|fix|perf|refactor|docs|test|ci|chore|style|build)"
    r"(?:\((?P<scope>[^\)]+)\))?"
    r"(?P<breaking>!)?"
    r":\s*(?P<subject>.+)$",
    re.IGNORECASE,
)


def run_command(cmd):
    """Executes a shell command and returns standard output."""
    try:
        res = subprocess.run(
            cmd,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            check=True,
            shell=isinstance(cmd, str),
        )
        return res.stdout.strip()
    except subprocess.CalledProcessError as e:
        sys.stderr.write(f"Command failed: {cmd}\nError: {e.stderr}\n")
        return ""


def get_commit_range(from_tag, to_ref):
    """Calculates git revision range."""
    if not from_tag:
        # Check if there is an existing tag
        latest_tag = run_command(["git", "describe", "--tags", "--abbrev=0"])
        from_tag = latest_tag if latest_tag else ""

    if from_tag:
        return f"{from_tag}..{to_ref}"
    return to_ref


def extract_commits(rev_range):
    """Extracts commit logs formatted as JSON-friendly dictionaries."""
    log_format = "%H%x1f%h%x1f%s%x1f%b%x1f%an%x1f%ad"
    cmd = ["git", "log", f"--pretty=format:{log_format}", "--date=short"]
    
    if ".." in rev_range:
        cmd.append(rev_range)
    else:
        cmd.extend(["-n", "50", rev_range])

    raw_output = run_command(cmd)
    if not raw_output:
        return []

    commits = []
    for line in raw_output.split("\n"):
        parts = line.split("\x1f")
        if len(parts) < 6:
            continue

        full_hash, short_hash, subject, body, author, date = parts[0], parts[1], parts[2], parts[3], parts[4], parts[5]
        
        # Parse conventional commit syntax
        match = CONVENTIONAL_PATTERN.match(subject)
        is_breaking = bool(match and match.group("breaking")) or ("BREAKING CHANGE" in body)
        
        c_type = match.group("type").lower() if match else "other"
        c_scope = match.group("scope") if match else None
        c_subject = match.group("subject") if match else subject

        commits.append({
            "hash": short_hash,
            "full_hash": full_hash,
            "raw_subject": subject,
            "type": c_type,
            "scope": c_scope,
            "subject": c_subject,
            "body": body.strip(),
            "author": author,
            "date": date,
            "is_breaking": is_breaking,
        })

    return commits


def categorize_commits(commits):
    """Groups commits by category for release note drafting."""
    categorized = {
        "breaking": [],
        "features": [],
        "fixes": [],
        "performance": [],
        "refactoring": [],
        "documentation": [],
        "maintenance": [],
        "other": [],
    }

    type_mapping = {
        "feat": "features",
        "fix": "fixes",
        "perf": "performance",
        "refactor": "refactoring",
        "docs": "documentation",
        "test": "maintenance",
        "ci": "maintenance",
        "chore": "maintenance",
        "build": "maintenance",
    }

    for c in commits:
        if c["is_breaking"]:
            categorized["breaking"].append(c)
        
        cat = type_mapping.get(c["type"], "other")
        categorized[cat].append(c)

    return categorized


def main():
    parser = argparse.ArgumentParser(description="Extract Git commits for Agent Skill release notes.")
    parser.add_argument("--from-tag", default="", help="Starting tag or revision")
    parser.add_argument("--to-ref", default="HEAD", help="Ending revision (default: HEAD)")
    parser.add_argument("--json", action="store_true", default=True, help="Output JSON structure")
    args = parser.parse_args()

    rev_range = get_commit_range(args.from_tag, args.to_ref)
    commits = extract_commits(rev_range)
    categorized = categorize_commits(commits)

    result = {
        "range": rev_range,
        "total_commits": len(commits),
        "categories": categorized,
    }

    print(json.dumps(result, indent=2))


if __name__ == "__main__":
    main()

# Release Notes - ${VERSION} (${DATE})

## 🌟 Overview
${OVERVIEW_SUMMARY}

---

## ⚠️ Breaking Changes
${BREAKING_CHANGES_LIST}

## 🚀 Features & Improvements
${FEATURES_LIST}

## 🐛 Bug Fixes
${BUG_FIXES_LIST}

## ⚡ Performance Improvements
${PERF_LIST}

## 🛠️ Internal & Maintenance
${MAINTENANCE_LIST}

---
**Full Changelog**: [${PREVIOUS_TAG}...${VERSION}](https://github.com/${REPO_OWNER}/${REPO_NAME}/compare/${PREVIOUS_TAG}...${VERSION})

# Conventional Commits Reference (v1.0.0)

Conventional Commits provide lightweight conventions on top of commit messages:

`<type>[optional scope]: <description>`

### Recognized Types
- **feat**: Introduces a new user-facing feature.
- **fix**: Patches a bug or regression.
- **perf**: Changes that improve execution performance.
- **refactor**: Code restructuring without bug fixes or new features.
- **docs**: Markdown or documentation updates only.
- **test**: Adding or correcting automated tests.
- **ci**: Pipeline and workflow script modifications.
- **chore**: Routine maintenance tasks or dependencies.

### Breaking Change Syntax
1. An exclamation mark before the colon: `feat(api)!: drop deprecated v1 auth endpoints`
2. An entry in the commit footer: `BREAKING CHANGE: The 'legacyAuth' flag has been removed.`

# Start interactive agent session
agy

# Prompt the agent
> Draft the release notes for our upcoming v2.4.0 release based on the latest commits

opencode "Generate changelog for release v2.4.0 using the release-notes skill"

claude "Prepare release notes for HEAD compared to last tag"

┌─────────────────────────────────────────────────────────────┐
│                 Skill Distribution Models                   │
├──────────────────────────────┬──────────────────────────────┤
│ 1. Git Submodule / Dotfiles  │ Shared across company repos  │
│ 2. Symlinked Central Cache   │ Developer ~/.config setup    │
│ 3. Skill Packs Archive       │ Packaged tarball distribution│
└──────────────────────────────┴──────────────────────────────┘

# Symlink your global skills into any active repository
mkdir -p .agents
ln -s ~/.gemini/antigravity-cli/skills .agents/skills

git submodule add https://github.com/your-org/agent-skills.git .agents/skills