github-profile-blocks

---
name: github-profile-blocks
description: This skill should be used when a GitHub profile README needs designed visual blocks instead of plain Markdown — hand-drawn cards, radar charts or timeline strips rendered with Pillow, light/dark theme switching, plus uploading the images and README through the GitHub Contents API. Trigger phrases include "主页做成设计卡片", "画好的 Block 插进 README", "换个高级字体", "雷达图放进板块", "把图推到 GitHub 主页". Not for TikZ academic figures (use academic-tikz) or general data plots for papers.
agent_created: true
---

# GitHub Profile Blocks

## Purpose

Turn a profile README into a set of deliberately designed, image-based blocks while keeping the page accessible and the text layer intact. Render every block locally with Pillow and system fonts so Chinese text is exact; never use AI image generation for content-bearing text. Produce light and dark versions of each image, wire them with `<picture>`/`prefers-color-scheme`, and publish through the GitHub Contents API with content-hash checks.

## When to use

- Building or restyling `owner/owner` profile README as designed cards.
- Replacing plain Markdown sections (intro, role understanding, experience, timeline) with drawn blocks.
- Adding hand-drawn radar charts or horizontal timeline strips inside a block.
- Iterating typography, contrast, layout (single column vs left-text/right-chart), or theme colours on an existing block set.
- Publishing regenerated images without producing empty commits or re-uploading unchanged files.

## Workflow

Read `references/workflow.md` for the full nine-step procedure, `references/typography.md` for font/size/stroke decisions, and `references/github_render.md` for README markup and API rules. Load a reference only when the current step needs it.

1. Fix the information architecture first: decide which blocks exist and what each one asserts. Do not start with colours.
2. Copy `content.example.json`, then edit `blocks`, `radar`, `timeline`, `themes` and `fonts` for the target profile.
3. Render with `scripts/render_blocks.py`. Inspect the produced PNGs visually before publishing — check title/subtitle spacing, clipped labels, stroke weight and bottom padding.
4. Compose the README with `<picture>` blocks, a clickable text section, a folded plain-text layer inside `<details>`, and descriptive `alt` text for every image.
5. Publish with `scripts/push_readme.py`. It skips unchanged assets by git blob sha, retries transient network errors, and backs up the previous online README.
6. Verify: compare remote blob shas with local files, fetch the rendered page to confirm `themed-picture` and rewritten image paths, and check key strings in the online README.

## Scripts

```bash
# Render all blocks + timeline for both themes
python scripts/render_blocks.py --config content.example.json --out ./output/assets

# Upload assets and README to the profile repository
python scripts/push_readme.py --repo Eastr5/Eastr5 --assets ./output/assets --readme ./README.md
```

`render_blocks.py` requires Pillow. `push_readme.py` requires the `gh` CLI authenticated with the `repo` scope; it obtains the token at runtime and never stores it. Profile `bio`/`location` updates need the separate `user` scope and are out of scope for these scripts.

## Hard constraints

- Keep the source of truth in `content.example.json` (or a project copy). Never hand-edit a rendered PNG.
- Keep the text layer: every image needs `alt`, and the README keeps a folded plain-text version so content is copyable, searchable and readable by screen readers.
- Use repository-relative image paths. GitHub rewrites them into `/owner/repo/raw/main/...` and wraps `<picture>` in `themed-picture`; absolute `raw.githubusercontent.com` URLs are unnecessary and may fail on restricted networks.
- Do not infer facts or numbers. When content is a judgement or a rough emphasis, label it as a schematic rather than a measurement — radar polygons are relative emphasis, not a capability score.
- Check Chinese line-breaking: punctuation and arrows must not start a line; avoid one-character orphan lines.
- Do not merge this skill into `academic-tikz` or literature skill repositories. It serves profile design, not academic figure generation.

## Common failures

Consult `references/typography.md` and `references/github_render.md` for detail. The highest-frequency ones: mixing logical width with physical font pixels during line wrapping (text occupies only half the card), stroke width 2 on a 3x canvas turning Kai typeface into bold sans, Kai/Latin glyph mismatch for abbreviations like "AI", and drawing a divider with nothing below it after a section is deleted.

• .gitignore 1 KB
• LICENSE 1 KB
• README.md 3 KB
• SKILL.md 5 KB
• content.example.json 4 KB