github-showcase

name	github-showcase
description	Generate LinkedIn and Facebook posts from any GitHub project as a styled Word document. Emoji-rich, detailed, copy-paste ready with embedded screenshots. Use when: "showcase my project", "create social media post", "promote my repo", "generate LinkedIn post for my GitHub project".

Social Media Showcase Generator

Generate LinkedIn and Facebook posts for a GitHub project, saved as a styled Word document in the project's social-media-posts/ folder.

Arguments

• $ARGUMENTS — GitHub repo name (e.g., Caffeinator) or full URL (e.g., https://github.com/user/repo)

Instructions

You are a developer content strategist creating engaging, emoji-rich social media posts. Your output is a Word document the user can open, copy, and paste directly into LinkedIn or Facebook.

Step 1: Gather Project Data

Extract the repo owner and name from $ARGUMENTS. If only a name is given, detect the user's GitHub account via gh api user.

Run these commands in parallel to gather data:

1. gh api repos/{owner}/{repo} — repo metadata (description, language, stars, topics)
2. gh api repos/{owner}/{repo}/readme --jq '.content' | base64 -d — full README
3. gh api repos/{owner}/{repo}/releases/latest — latest release (if any)
4. gh api repos/{owner}/{repo}/languages — language breakdown

Read the README carefully. Identify:

• The problem it solves (the "why")
• Key features (3-5 most impressive)
• Technical highlights (interesting implementation details, APIs used)
• Target audience (who would care)
• Unique selling point (what makes it different)

Step 2: Find the Local Project Directory

Check common project locations on the user's machine:

• D:\Projects\{repo_name}\
• ~/projects/{repo_name}/
• Current working directory

If you cannot determine the local path, ask the user.

Step 3: Collect Screenshots

Look for existing screenshots/images in the project directory:

• assets/ folder (banner.png, screenshot.png, etc.)
• screenshots/ folder
• docs/images/ folder
• Any .png, .jpg, .gif files in common locations

Collect the paths of all found images — these will be embedded in the Word document.

Step 4: Generate Content

Write content for LinkedIn and Facebook. Follow these rules strictly:

Both Platforms — General Rules

• Use emojis generously throughout (section headers, bullet points, transitions)
• NEVER start with "I'm excited to announce" or "Thrilled to share" — these get scrolled past
• Start with a hook: a problem statement, surprising fact, or relatable frustration
• Be DETAILED — this is not a teaser, it's a full showcase post (1200-2000 characters)
• Include the story: why you built it, what problem it solves, how it's different
• Include 4-6 feature bullet points with emojis
• Include a brief technical note (what stack, what APIs — keep it accessible)
• Include a personal reflection (what you learned, what surprised you)
• End with a CTA (try it, star it, give feedback, link)
• End with 4-6 relevant hashtags

LinkedIn-Specific Rules

• Professional but personal tone — tell the builder's story
• Use line breaks liberally (LinkedIn rewards scroll-stopping, airy formatting)
• Mention the GitHub link at the end (tip in the doc says to put it in the first comment)
• Hashtags: #opensource #github #buildinpublic #sideproject + language-specific

Facebook-Specific Rules

• Slightly more casual and conversational than LinkedIn
• Can be a bit more fun/personal — Facebook audiences respond to personality
• Include the GitHub link directly in the post body
• More emoji-forward than LinkedIn
• Hashtags: #coding #opensource #sideproject #developer + language-specific

Visual Content Tips

Generate a short section with:

1. What demo GIF to record (15-30 seconds, what workflow to show)
2. What screenshots to attach when posting (which views/states)
3. Social preview image suggestion (for GitHub repo settings, 1280x640)

Step 5: Write Content File and Generate Word Document

1. Write the content to a temporary file using this exact format:

===LINKEDIN===
(full LinkedIn post content here)
===FACEBOOK===
(full Facebook post content here)
===VISUAL_TIPS===
(visual content recommendations here)

2. Ensure python-docx is installed (pip install python-docx if not).

3. Save this temp file, then run the generator script that ships with this skill:

python <skill_scripts_dir>/showcase_generator.py \
  --project-dir "<local_project_path>" \
  --project-name "<ProjectName>" \
  --content "<temp_content_file>" \
  --github-url "https://github.com/{owner}/{repo}" \
  --screenshots <path1> <path2> ...

The script location depends on where the skill is installed:

• User-level: ~/.claude/skills/github-showcase/scripts/showcase_generator.py
• Project-level: .claude/skills/github-showcase/scripts/showcase_generator.py

4. Clean up the temp content file after generation.

5. Tell the user:

   • The exact path to the generated Word document
   • How many screenshots were embedded
   • Remind them: "Open the file, copy the content for your platform, and paste it directly into your post composer. Attach the screenshots from the document or from your project's assets folder."

Important Notes

• The Word document goes in {project_dir}/social-media-posts/ — the script creates this folder automatically
• The filename format is {ProjectName}_Showcase_{YYYY-MM-DD}.docx
• If screenshots exist in the project, ALWAYS embed them — visuals are critical for engagement
• Make the content copy-paste ready — no markdown syntax, no formatting marks, just plain text with emojis and line breaks
• The content should be DETAILED and CATCHY — not a bare summary. Think "viral developer post" energy.
• Requires python-docx — prompt the user to install it if missing