How to Add Snake Contribution Animation to Your GitHub Profile README

The Platane/snk project generates an SVG animation that overlays a snake path on your GitHub contribution calendar. Each green square in your contribution history becomes a piece of food the snake eats as it moves across the grid. The result is a unique animated visualization of your commit activity that is both eye-catching and technically interesting.

Two versions are generated: one for light mode and one for dark mode. Using the HTML <picture> element with prefers-color-scheme, your README automatically serves the correct version based on each visitor's system preference. This means your profile looks great whether someone uses GitHub's light or dark theme.

Follow these steps to configure the GitHub Action:

1. In your GitHub profile repository, create .github/workflows/snake.yml:

name: Generate Snake
on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:
permissions:
  contents: write
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: Platane/snk@v3
        with:
          github_user_name: ${{ github.repository_owner }}
          outputs: |
            dist/github-contribution-grid-snake.svg
            dist/github-contribution-grid-snake-dark.svg?palette=github-dark

2. Run the workflow manually from Actions → Generate Snake → Run workflow to generate the files.
3. Add to your README:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="dist/github-contribution-grid-snake-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="dist/github-contribution-grid-snake.svg">
  <img alt="snake" src="dist/github-contribution-grid-snake.svg">
</picture>

The snake color and background are configurable through the palette query parameter in the output path. The default generates a green snake on a light background. For a custom color scheme, you can specify colors directly: dist/snake-custom.svg?color_snake=orange&color_dots[]=0,0,0,15&color_dots[]=0,0,0,60&color_dots[]=0,0,0,85&color_dots[]=0,0,0,100.

The schedule runs at midnight UTC by default. You can change the cron expression to regenerate less frequently (weekly: 0 0 * * 0) or keep daily updates for profiles with consistent contribution activity. The generated SVG files are committed to the dist/ folder automatically by the Action — no manual steps needed after the initial setup.

If the workflow fails with a permissions error, verify that the workflow has permissions: contents: write set in the YAML. GitHub's default workflow permissions changed in 2023 — older Action configurations that worked before may now require this explicit permission block.

If the snake renders but appears blank or shows no contribution data, check that the github_user_name input matches your exact GitHub username (case-sensitive). If the <picture> element shows both images stacked rather than switching, verify you are using raw GitHub content URLs — the dist/ path in the snippet above resolves correctly when the images are in your profile repository (username/username).