animated-github-profile – Coding skill for AI agents

Animated GitHub Profile Skill

A comprehensive guide and agent instruction set for designing, generating, and deploying animated GitHub profile READMEs that work within GitHub's JavaScript restrictions using pure SVG and CSS/SMIL animations.

---

When to Use This Skill

• Use when designing, revamping, or generating an animated GitHub profile README (username/username).
• Use when working within GitHub's Markdown HTML sanitization to render interactive or motion elements using pure SVG, CSS @keyframes, and SMIL.
• Use when creating theme-adaptive assets (dark/light mode) using <picture> elements.
• Use when automating dynamic contribution graphs, snakes, or 3D cityscapes via GitHub Actions.

---

Why SVG Animations?

1. GitHub Security Model: GitHub sanitizes all Markdown files and strips out all <script> tags, inline JavaScript, and iframes. Normal web motion libraries (Framer Motion, GSAP, Three.js) cannot execute in a GitHub README.

2. Native SVG Motion: Pure SVG with @keyframes CSS and SMIL (<animate>, <animateTransform>) is one animation option; animated GIFs are another, and SVG animation support varies by browser and image context.

3. Zero Third-Party Downtime: Unlike external status generators (e.g., github-readme-stats, shields.io) that frequently fail when GitHub API rate-limits are reached, self-contained SVGs committed to the profile repository avoid a live third-party generator dependency, though rendering and cache behavior still need testing.

---

Architectural Layout

A top-tier animated profile combines the following modules stacked vertically in README.md:

┌────────────────────────────────────────────────────────┐
│ 1. HERO BANNER (Dark / Light Auto-Switching via <picture>)
│    - Typing terminal prompt & blinking cursor          │
│    - Shimmering gradient name (letter-by-letter reveal)│
│    - Cycling typed role headlines                      │
│    - Hologram scanline laser sweep                     │
│    - Live code editor typing real project snippet      │
├──────────────────────────┬─────────────────────────────┤
│ 2. SWINGING LANYARD      │ 3. 3D TECH ORBIT            │
│    - Damped pendulum     │    - Satellites orbiting    │
│      swing physics       │      an atomic core         │
│    - Holographic glare   │    - Categorized capability │
│    - Avatar & barcode    │      matrix                 │
├──────────────────────────┴─────────────────────────────┤
│ 4. FEATURED ENGINEERING & WORKFLOW PROJECTS (Markdown) │
├────────────────────────────────────────────────────────┤
│ 5. AUTOMATED CONTRIBUTION VISUALIZER                   │
│    - Snake eating contribution dots (Platane/snk) OR   │
│    - 3D Isometric Night Skyline City                   │
├────────────────────────────────────────────────────────┤
│ 6. VERIFIED TECH BADGES & CONNECT LINKS                │
└────────────────────────────────────────────────────────┘

---

Step-by-Step Implementation Workflow

Step 1: Character Art / Avatar Generation

Prompt any AI image generator (ChatGPT/DALL-E, Midjourney, Gemini) to generate a clean character illustration. A pure white or transparent background is critical for clean cutouts.

Master Character Prompt:

High-quality anime-style digital illustration of a young developer sitting relaxed in a sleek modern ergonomic chair with a dark laptop on their lap, softly smiling at the viewer. Sunglasses resting on head, wearing a cozy dark zip-up hoodie over a tech t-shirt, jeans. Beside them on a small glass-top table: a stack of programming books with spines reading "Python", "Agentic AI", "Docker", "System Architecture"; a takeaway coffee cup with "Code. Coffee. Repeat." written on it; and a small potted desk plant. Pure white background, warm soft rim lighting, clean detailed anime art style, vibrant colors, high resolution, full body in frame.

*Tip: Generate 3–4 variations and select the one with the cleanest edges and clearest facial crop for the lanyard badge.*

---

Step 2: Generate Core Animated SVGs

Use the master prompts below with an AI coding assistant to create standalone SVG files.

1. Hero Banner (banner.svg & banner-light.svg)

• Dimensions: viewBox="0 0 1200 480" (responsive, width="100%").
• Left Section:
• macOS window control dots (#ef4444, #f59e0b, #10b981).
• Live status pill with pulsing green indicator (OPEN TO COLLABS).
• Terminal greeting $ whoami --verbose.
• Bold name with animated multi-stop SVG gradient shimmer.
• Cycling role headlines using CSS @keyframes with staggered opacities.
• Value proposition and meta pills (Location, Experience, Roles).
• Right Section:
• Simulated IDE code editor window (0.95 opacity).
• Syntax-highlighted code snippet typing out core domain logic (e.g. Python, Agentic AI, TypeScript).
• Blinking rectangular cursor (#22d3ee).
• Motion FX:
• Full-width laser scanner bar sweeping top-to-bottom on a 4.5s loop.
• Ambient blurred background orbs with subtle breathing animations.
• Light Palette Variant (banner-light.svg):
• Background: #ffffff to #f8fafc with slate grid.
• Shimmer colors: #0284c7 to #7c3aed to #db2777.
• Code card: Crisp light theme with high contrast dark text.

2. Swinging Lanyard ID Badge (lanyard.svg)

• Dimensions: viewBox="0 0 460 380".
• Visual Components:
• Woven fabric strap entering from above the canvas.
• Metallic clasp, swivel ring, and badge slot hole.
• Glassmorphic card body with rounded corners (rx="16").
• Golden smart-card chip IC.
• Neon-bordered avatar circle.
• Developer metadata (Name, Title, Clearance Level, City).
• Vector barcode lines with unique serial tag (SN-007-PASS).
• Physics & Motion:
• Damped pendulum swing on initial load:

    @keyframes lanyardSwing {
      0%   { transform: rotate(11deg); }
      15%  { transform: rotate(-8deg); }
      30%  { transform: rotate(5.5deg); }
      45%  { transform: rotate(-3.5deg); }
      60%  { transform: rotate(2deg); }
      75%  { transform: rotate(-1deg); }
      100% { transform: rotate(0deg); }
    }
    

• Infinite subtle ambient drift (±0.8deg).
• Diagonal holographic glare bar moving across the card every 4s.

3. Tech Orbit System (stack.svg)

• Dimensions: viewBox="0 0 680 380".
• Visual Components:
• Glowing central core representing the developer's primary specialization.
• Three concentric elliptical orbits (Inner, Middle, Outer) with dashed orbital paths.
• Planetary satellites (Python, Docker, TypeScript, Playwright, CI/CD) revolving at independent speeds (18s, 26s, 36s).
• Right-side capability matrix detailing core architectural pillars and experience metrics.

---

Step 3: Setup Contribution Visualizer Workflows

Create automated GitHub Actions to regenerate contribution activity on a daily schedule.

Option A: Contribution Snake (.github/workflows/snake.yml)

name: Generate Snake Contribution Animation

on:
  schedule:
    - cron: "0 0 * * *" # Runs daily at midnight UTC
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: write

jobs:
  generate:
    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:
      - name: Generate snake.svg
        uses: Platane/snk/svg-only@d8f6715049803e982ee5ff501b6b9b7d5deeb09b
        with:
          github_user_name: ${{ github.repository_owner }}
          outputs: |
            dist/github-contribution-grid-snake.svg
            dist/github-contribution-grid-snake-dark.svg?palette=github-dark&color_snake=#38bdf8&color_dots=#161b22,#0e4429,#006d32,#26a641,#39d353
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Push snake animation to output branch
        uses: crazy-max/ghaction-github-pages@c0d7ff0487ee0415efb7f32dab10ea880330b1dd
        with:
          target_branch: output
          build_dir: dist
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Option B: 3D Contribution City Skyline (.github/workflows/profile-3d.yml)

name: GitHub 3D Contribution Calendar

on:
  schedule:
    - cron: "0 18 * * *"
  workflow_dispatch:

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
        with:
          persist-credentials: true # Required only for this authorized generated-asset push.
      - uses: yoshi389111/github-profile-3d-contrib@f4cf497614310d7b45ab3e000a523e47c524b14f
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          USERNAME: ${{ github.repository_owner }}
      - name: Commit & Push
        run: |
          git config user.name github-actions
          git config user.email [email protected]
          git add -- profile-3d-contrib
          if git diff --cached --quiet; then exit 0; fi
          

… (full content is in the download package)