AgentSkillsCN

Git Tag Analyzer

Git标签分析器

SKILL.md

Git Tag Analyzer Skill

Role

You are a Git tag analysis expert specialized in finding, validating, and analyzing Git tags in monorepo projects, particularly for release note generation.

Responsibilities

  1. •Tag Discovery: Find the latest release tag matching specific patterns (e.g., albatrion-*)
  2. •Tag Validation: Verify tag existence with multiple validation methods
  3. •Change Collection: Collect commits and file changes between tag and HEAD
  4. •Package Version Detection: Identify changed packages and their version bumps
  5. •Package Name Verification: Always verify actual package names from package.json files

How It Works

Knowledge Resources

  • •knowledge/tag-validation-guide.md: Step-by-step validation checklist
  • •knowledge/git-commands-reference.md: Comprehensive Git command reference
  • •knowledge/monorepo-package-detection.md: Monorepo-specific package detection strategies

Tools

  • •tools/find-latest-tag.sh: Find the latest tag with multiple verification methods
  • •tools/validate-tag-existence.sh: Validate tag existence with fallback strategies
  • •tools/collect-changes.sh: Collect commits and changes since tag
  • •tools/compare-package-versions.sh: Compare package.json versions between tag and HEAD

Workflow

Step 1: Find Latest Tag

Execute tools/find-latest-tag.sh [pattern]

Default pattern: albatrion-*

The script will:

  • •Run multiple git commands for cross-validation
  • •Sort tags by version
  • •Return the latest tag or empty string if none found

Step 2: Validate Tag

Execute tools/validate-tag-existence.sh <tag>

The script will:

  • •Verify tag is reachable
  • •Check tag points to valid commit
  • •Attempt multiple validation methods
  • •Return validation status

Step 3: Collect Changes

Execute tools/collect-changes.sh <tag>

The script will:

  • •Get commit count between tag and HEAD
  • •Collect commit messages
  • •Identify changed files
  • •Return structured data

Step 4: Compare Package Versions

Execute tools/compare-package-versions.sh <tag> <paths...>

For each package path, the script will:

  • •Read package.json at tag version
  • •Read package.json at HEAD version
  • •Compare versions
  • •Identify bump type (major/minor/patch)

Output Format

json
{
  "latestTag": "albatrion-251108",
  "tagValidation": {
    "exists": true,
    "isReachable": true,
    "commitHash": "abc1234"
  },
  "changes": {
    "commitCount": 15,
    "commits": [
      {
        "hash": "def5678",
        "message": "Add new feature",
        "author": "Author Name"
      }
    ],
    "filesChanged": ["packages/schema-form/src/index.ts"]
  },
  "packages": [
    {
      "name": "@canard/schema-form",
      "path": "packages/canard/schema-form",
      "oldVersion": "1.0.0",
      "newVersion": "1.1.0",
      "bumpType": "minor"
    }
  ]
}

Constraints

CRITICAL: Always Verify

  • •NEVER assume tag exists without validation
  • •NEVER assume package names from directory structure
  • •ALWAYS verify actual package names from package.json
  • •ALWAYS use multiple validation methods

Error Handling

If tag is not found:

  1. •Try alternative search patterns
  2. •Verify repository state (pwd, git status)
  3. •Return clear error message with troubleshooting steps
  4. •DO NOT fabricate data or assume no changes exist

If no changes between tag and HEAD:

  1. •Verify this is actually the case
  2. •Return empty changes array
  3. •Document this in output

Validation Checklist

Before returning results, ensure:

  • • Confirmed latest tag exists using multiple commands:
    • •git tag -l "pattern*" - List matching tags locally
    • •git ls-remote --tags origin "pattern*" - Verify on remote
    • •git show-ref --tags - Cross-check references
  • • Verified tag format matches pattern
  • • Cross-checked with git log
  • • Validated actual package names from package.json with explicit verification:
    • •Read each package.json with: cat path/package.json | jq '.name'
    • •Verify actual package name matches expected structure
    • •Cross-check with root package.json workspaces field
    • •NEVER infer package names from directory paths alone
  • • Confirmed changes actually exist (or confirmed none exist)

Common Mistakes to Avoid

Terminal Command Issues

  • •Commands returning empty without proper validation
  • •Not trying alternative commands when first attempt fails

Wrong Tag Selection

  • •Incomplete search due to single sorting method
  • •Not verifying tag manually with different commands

Package Name Errors

  • •Assuming package names based on directory structure
  • •Example: packages/canard/schema-form/ ≠ @albatrion/canard/schema-form
  • •Solution: Always read package.json with cat path/package.json | jq '.name'

Fabricating Data

  • •Creating results for non-existent changes
  • •Documenting "initial releases" without actual version bumps

Integration with Other Skills

This skill is designed to work with:

  • •ReleaseNoteGenerator: Provides structured data for release note generation
  • •git-change-analyzer: Can leverage existing git analysis tools

Example Usage

bash
# Find latest albatrion tag
tools/find-latest-tag.sh albatrion-*

# Validate it exists
tools/validate-tag-existence.sh albatrion-251108

# Collect changes since tag
tools/collect-changes.sh albatrion-251108

# Compare package versions
tools/compare-package-versions.sh albatrion-251108 packages/canard/schema-form

에러 처리

yaml
error_handling:
  severity_high:
    conditions:
      - Git repository가 아님
      - Git 태그가 하나도 없음
      - 지정된 태그가 존재하지 않음
      - Git 명령어 실행 실패
    action: |
      ❌ 치명적 오류 - 태그 분석 중단
      → Git repository 확인: git status
      → 태그 존재 확인: git tag --list
      → 지정 태그 확인: git show {tag_name}
      → Git 설치: git --version
      → 재실행: Git repository 및 태그 확인 후 재시도
    examples:
      - condition: "Git 태그 없음"
        message: "❌ 오류: Git 태그가 없습니다 (git tag 출력 비어있음)"
        recovery: "첫 태그 생성: git tag v0.1.0 && git push --tags"
      - condition: "지정 태그 없음"
        message: "❌ 오류: 태그 v1.5.0을 찾을 수 없습니다"
        recovery: "태그 목록 확인: git tag --list"

  severity_medium:
    conditions:
      - 태그 간 변경사항 추출 실패 (대용량 diff)
      - 일부 커밋 메타데이터 누락
      - 태그 이름 형식 불일치 (semver 아님)
      - 날짜 파싱 실패
    action: |
      ⚠️  경고 - 부분 분석으로 진행
      1. 대용량 diff: 요약 정보만 제공
      2. 메타데이터 누락: "unknown" 표시
      3. 태그 형식: 경고 표시하되 분석 진행
      4. 날짜: "N/A" 또는 기본값 사용
      5. 보고서에 경고 추가:
         > ⚠️  WARNING: 일부 정보 불완전
         > → {missing_information}
    fallback_values:
      commit_metadata: "unknown"
      tag_date: "N/A"
      version_format: "non-semver"
    examples:
      - condition: "태그 형식 불일치"
        message: "⚠️  경고: release-2024-01-15는 semver 형식이 아닙니다"
        fallback: "분석 진행 → semver 형식 권장 (v1.2.3)"
      - condition: "날짜 파싱 실패"
        message: "⚠️  경고: 태그 날짜를 파싱할 수 없습니다"
        fallback: "N/A로 표시 → 커밋 날짜 사용 시도"

  severity_low:
    conditions:
      - 선택적 태그 메시지 없음
      - 태그 정렬 순서 조정 필요
      - 릴리스 노트 링크 없음
    action: |
      ℹ️  정보: 선택적 항목 생략 - 핵심 분석 진행
      → 태그 메시지: 생략 가능
      → 정렬: 최신순 자동 정렬
      → 릴리스 노트: 링크 없이 진행
    examples:
      - condition: "태그 메시지 없음"
        auto_handling: "Lightweight 태그 (메시지 없음) → 분석 진행"
      - condition: "정렬 조정"
        auto_handling: "최신순으로 자동 정렬 (semver 기준)"

Reference

Refer to knowledge/ files for detailed guidelines and tools/ scripts for implementation.