Animated GitHub Profile Skill

A comprehensive guide and agent instruction set for designing, generating, and deploying animated GitHub profile READMEs that bypass 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 bypassing 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?

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.
Native SVG Motion: Pure SVG with @keyframes CSS and SMIL (<animate>, <animateTransform>) is the only animated format natively supported across all browsers without external dependencies.
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 render with 100% reliability.

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
      - 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 github-actions@github.com
          git add -A .
          git commit -m "Generated 3D Profile Calendar" || exit 0
          git push

Step 4: Assembling the `README.md`

Use HTML <picture> elements for native dark/light mode switching and add cache-busting queries:

<div align="center">

  <!-- Responsive Auto-switching Hero Banner -->
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="banner.svg?v=1">
    <source media="(prefers-color-scheme: light)" srcset="banner-light.svg?v=1">
    <img src="banner.svg?v=1" width="100%" alt="Hero Banner">
  </picture>

  <br><br>

  <!-- Lanyard ID Badge & Capabilities Orbit -->
  <p align="center">
    <img src="lanyard.svg?v=1" width="41%" alt="ID Badge">
    <img src="stack.svg?v=1" width="57%" alt="Tech Orbit">
  </p>

</div>

---

### ⚡ About Me
> **[Your Role / Identity Headline]**  
> [Concise 2-sentence summary of your specialization, experience, and passions].

- 🤖 **Current Focus:** [Core projects or frameworks]
- 🎓 **Education & Mentorship:** [Courses, teaching, or open source curricula]
- 💬 **Ask Me About:** [Key technical domains]

---

### 🚀 Featured Engineering Projects

| Repository | Focus & Capabilities | Tech Stack | Link |
| :--- | :--- | :--- | :---: |
| [**Project 1**](https://github.com/user/project1) | Brief high-impact description of the problem solved. | `Python` `AI` `Docker` | [**Explore Repo →**](https://github.com/user/project1) |
| [**Project 2**](https://github.com/user/project2) | Educational tutorial or platform tool. | `TypeScript` `Playwright` | [**Explore Repo →**](https://github.com/user/project2) |

---

### 🐍 Contribution Activity

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/<USER>/<USER>/output/github-contribution-grid-snake-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/<USER>/<USER>/output/github-contribution-grid-snake.svg">
    <img src="https://raw.githubusercontent.com/<USER>/<USER>/output/github-contribution-grid-snake.svg" alt="Contribution Snake" width="100%">
  </picture>
</div>

---

### 📫 Connect & Collaborate

<p align="center">
  <a href="https://linkedin.com/in/<username>"><img src="https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" alt="LinkedIn" /></a>
  &nbsp;&nbsp;
  <a href="mailto:<email>"><img src="https://img.shields.io/badge/Email-EA4335?style=for-the-badge&logo=gmail&logoColor=white" alt="Email" /></a>
  &nbsp;&nbsp;
  <a href="https://github.com/<username>"><img src="https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub" /></a>
</p>

Critical Rules & Technical Gotchas

1. The GitHub CDN Cache-Busting Rule (`?v=1` ➔ `?v=2`)

GitHub proxies and caches all images through Camo CDN (camo.githubusercontent.com).
Symptom: You update an SVG file, push to GitHub, and the profile displays the old version.
Fix: Always append a query version parameter to local links in README.md (banner.svg?v=1). Whenever you edit an SVG, bump the parameter (?v=2).
Order of Operations:
1. Commit and push the updated SVG files first.
2. Commit and push the README.md with the bumped version number second.

2. Base64 Image Encoding (PNG over WebP)

When embedding portraits, cutouts, or textures into an SVG via <image href="data:image/png;base64,..." />, always use PNG format.
Safari (especially on iOS / older macOS) fails to decode Base64 WebP inside standalone SVGs.

3. XML Entity Escaping

Standalone SVGs are strictly parsed as XML documents.
Forbidden: Unescaped ampersands (&), less-thans (<), or greater-thans (>) anywhere in the document—including inside CSS comments.
Always escape them (&, <, >) or wrap <style> blocks in <![CDATA[ ... ]]>.

4. Generous Text Reveal Windows (No Font Clipping)

Operating systems compute font line-heights and ascender/descender metrics differently (macOS vs Windows vs Linux).
When creating typing reveal clipping paths (<clipPath>), ensure height and padding around the text are generous (at least 8–12px padding above and below) so letters like g, y, p, and j are never sliced off.

5. Fallback States for Animation-Disabled Environments

Some clients disable CSS animations (e.g. prefers-reduced-motion or static vector viewers).
Always apply animation-fill-mode: both and ensure initial SVG elements define valid default coordinates and opacities so the card displays complete information even without animation.

6. Unique ID Namespacing

If multiple SVGs share identical gradient IDs (e.g. <linearGradient id="bg-grad">), browsers can cross-contaminate styles when rendered together on the same HTML page.
Namespace all IDs per file: e.g. banner-bg-grad, lanyard-card-grad, orbit-core-grad.

Limitations

No Arbitrary Script Execution: GitHub's HTML sanitizer permanently strips inline <script> tags, event listeners (onclick), and external JavaScript libraries; interactive games or dynamic DOM manipulation within markdown are not supported.
Camo CDN Caching: Dynamically updated external SVGs may experience caching delays unless appropriate Cache-Control headers are served or query parameters are bumped.
Rendering Performance: Large numbers of complex SVG filter primitives (e.g., <feGaussianBlur> with high radius) or deeply nested SMIL loops can increase client CPU and battery usage on mobile devices.

Security & Safety Notes

When using GitHub Actions to push generated assets to a profile repository, grant least-privilege token permissions (contents: write).
Verify third-party action SHAs and avoid exposing private tokens or email addresses in public SVG configs.

Checklist for Production Release

Repository created with exact username match (username/username).
Character image generated with high contrast and transparent/white background.
banner.svg and banner-light.svg tested locally in both dark and light modes.
All SVGs validated through an XML parser with 0 syntax errors.
All IDs in SVGs properly namespaced to prevent style collisions.
GitHub Actions workflow permission toggled to Read and write permissions in repo settings.
Contribution workflow executed successfully and output branch populated.
Version query parameter (?v=1) verified on all image links in README.md.
Profile links (LinkedIn, Email, featured repos) verified with active URLs.

Related Skills

@github-presence — Comprehensive README structure, SEO, and discoverability.
@github-actions — Building and debugging automated CI/CD workflows.