Sync Github Content

Sync GitHub content (Projects / Blog)

Scope

This skill keeps project pages aligned with GitHub work. It does not replace sync-public-identity (homepage / voice / tags from identity.md).

Do first

1. Read github-content-index.md at the repo root.
2. Read identity.md Allowed tags only (and voice if writing copy).
3. Confirm gh auth status works (private repos need a logged-in gh).

Hard rules

No fabricated screenshots

Never use GenerateImage or any AI image tool to invent app UIs, docs pages, or “what it might look like.”

Acquisition order (stop at first success):

1. Reuse an honest file already under static/images/projects/ for that project.
2. Copy a real screenshot from the source repo (README, docs/) or product site into static/images/projects/<slug>.png.
3. Capture from a live public URL (Playwright / browser tooling) when available.
4. Ask the user for a file if the app is local-only, private, or needs auth.
5. Omit image: in frontmatter and list “needs real screenshot” in the report.

Missing image is better than a lie. Do not “fix” bad art by regenerating UI with AI.

No draft frontmatter

Write normal Hugo content files the user reviews in git before commit. Do not set draft: true.

No blog-per-project

Every approved repo should get a project page when missing. Do not invent a blog post for each project. Blog only when there is a clear story (release, substantial rewrite, narrative milestone). Default: propose in the report; write a blog file only after the user confirms in the same run.

Site voice (same as identity sync)

• No em dashes (—).
• No MHCG / consultancy / Care Plan sales copy on this site.
• Tags: allowed list in identity.md only. Leave categories empty.
• Plain, precise, slightly dry tone.

Index maintenance

github-content-index.md is the approval record.

Not in index → treat as pending on scan.

Auto-skip without asking: forks; archived repos (report only); markheydon/markheydon.github.io.

After the user decides, move the repo block into the correct section and set notes.

Workflow

1. Load local state

• Parse index sections and repo blocks.
• Scan content/projects/*.md and content/blog/*.md for GitHub URLs in links, body, and frontmatter.
• Build map: owner/repo → project path, blog paths, image: paths.

2. List GitHub repos

gh repo list markheydon --limit 1000 \
  --json name,url,isPrivate,isFork,isArchived,description,pushedAt,updatedAt

Drop forks. Respect index excluded. Compare to index + local content.

3. Pending / unknown repos

If any non-fork, non-archived repo is pending or absent from the index, stop and ask before writing content. Present a compact table:

| Repo | Private? | Description | Last push |

For each: user chooses showcase or excluded (+ optional note). Update the index.

Do not write project pages for excluded or still-pending repos.

4. Project gaps

For each showcase repo where project: is empty or the file is missing:

Create content/projects/<slug>.md matching existing pages (see solo-dev-board.md, monolog-wp-cli.md):

---
title: "..."
date: YYYY-MM-DD
tags: [...]
summary: "..."
description: "..."
badges: [...]
links:
  - icon: fab fa-github
    url: https://github.com/markheydon/<repo>
---

Sections: Overview, Technologies Used, Key Features (if applicable), Repository.

• Pull facts from repo README / description via gh repo view or README fetch. Do not invent features.
• Private repos: high-level copy only; strip client/confidential detail.
• image: only if a real file exists or was just captured (see screenshot rules).
• Update index project: path and image: status.

Known gaps in the seeded index: UnmessyCleanExample, turpinverse.

5. Blog candidates (strict)

Flag blog: candidate only when all apply:

• Repo is showcase.
• No existing related blog post.
• Clear narrative signal: e.g. v1.0 release, major rewrite, new public tool worth a story.
• Not routine commits, dependency bumps, or “we should have a post.”

Default: list proposals in the final report with one-line rationale. Write content/blog/<slug>.md only if the user already said yes in this conversation.

Reuse project image: only when the file exists on disk; same screenshot rules.

6. Stale / orphan (report only)

• Stale: showcase project page vs repo pushedAt / releases clearly out of date (mention; do not auto-rewrite).
• Orphan: project page with no matching GitHub repo in index or gh list (flag; do not delete).

7. Image audit

Run:

bash .cursor/skills/sync-github-content/scripts/audit-project-images.sh

Report every MISS line. Cross-check index Image audit snapshot section. Remind: replace hallucinated art with real captures; omit image: until then.

Optionally update index image: fields for showcase repos when status changes.

8. Final report

Always include:

1. Index changes (repos moved showcase / excluded / pending cleared).
2. Files created or updated (paths only).
3. Project gaps filled vs still open.
4. Blog proposals (or “none”).
5. Screenshot todos (missing file, needs capture, ready).
6. Stale / orphan flags if any.
7. Reminder: new files are local until the user commits; run /sync-identity if homepage copy changed separately.

Project page slug hints

Done when

• Index reflects user decisions for all scanned repos (or scan stopped at pending for user input).
• Every showcase repo has a project page path in the index and on disk (or is explicitly blocked pending screenshot-only work with page written without image:).
• No new AI-generated UI screenshots were added.
• Image audit results are in the report.
• User knows what to proofread before commit.