linuz90/share-pretty-gist

Share Pretty Gist

Package and share content as a beautifully rendered GitHub Gist on gists.sh.

When to Use

Use this skill when the user wants to share content with others, not just store it. Triggers include:

• "Share this as a gist"
• "Make a shareable link for this code/report/doc"
• "Package this for someone to read"
• "Send this to [person] as a gist"
• Any request to create a gist where the emphasis is on presentation and readability

This is different from plain gist creation (storage) because it focuses on structuring the content so it renders beautifully on gists.sh.

Workflow

Step 1: Prepare the content

Infer from context what the user wants to share. Use good judgment on structure:

• Code: Use the correct filename with proper extension (e.g. server.ts, config.yml, query.sql) so Shiki highlights it correctly. Add a brief comment header if context would help the reader.
• Report/doc: Use a .md file. Structure with clear headings, bullet points, and GFM alerts where appropriate.
• Tutorial/guide: Use a .md file. Use numbered steps, language-tagged code blocks, and > [!TIP] / > [!NOTE] alerts for callouts.
• Quick share (snippet, error log, config): Use the most fitting extension. Keep it minimal.

For multi-file gists, put the most important file first (it displays by default as the first tab on gists.sh).

If it's obvious from the context that there's some specific text or markdown content to share, put it in the gist with no changed or only minor formatting ones as needed.

NEVER put meta-commentary in the gist content, like "This is what {user name} asked me to share...".

Step 2: Create the gist

gh gist create <files> -d "Clear description of what this contains"

The -d description becomes the title on gists.sh, so make it descriptive and useful.

If gh is not available or authenticated, guide the user through the installation and setup.

Step 3: Warm the cache

After creating the gist, fetch the gists.sh page once to warm up the cache, so it loads instantly for the reader:

curl -s https://gists.sh/{user}/{id} > /dev/null

Step 4: Present the URL

Show gists.sh as the primary shareable link:

-> https://gists.sh/{user}/{id}

(original on GitHub: https://gist.github.com/{user}/{id})

Rules

• ALWAYS create SECRET gists. Even when asked to "share with someone" or "share externally", the gist must be secret. Only use --public if the user EXPLICITLY asks for a public gist.
• Always include -d with a clear, concise, but descriptive title. This is the first thing readers see on gists.sh.
• Use correct filenames with proper extensions (e.g. server.ts, config.yml, Dockerfile) so syntax highlighting works correctly.
• Use natural, descriptive filenames. Never prefix filenames with redundant words like "gist-" or "shared-" (e.g. use README.md not gist-readme.md, use setup-guide.md not gist-setup-guide.md).
• Always warm the cache after creating or updating a gist.
• Try to avoid using em dashes in any content, unless they're already in the original content to share.
• No meta-commentary ("The user asked me to...", "Here is a summary of..."). Get straight to the content.
• Write for the reader, not the creator. The person opening the link should understand the content without needing the original conversation context.

gists.sh Rendering Tips

• Try to use language tags on all code blocks (```typescript, ```yaml, etc.) for proper syntax highlighting.
• GFM alerts also can be used because they render nicely: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION].
• Avoid raw HTML unless strictly necessary. Stick to standard GitHub Flavored Markdown.
• Multi-file gists render as tabs on gists.sh. The first file is shown by default.
• Tables, task lists, and other GFM features all work.
• YAML front matter in markdown files renders as a structured table above the content.
• Structured data files get interactive viewers: JSON/GeoJSON (collapsible tree), YAML (tree), CSV/TSV (sortable table), ICS/iCal (calendar cards). Use proper file extensions so the viewer activates.
• Link to a specific file in a multi-file gist with ?file={filename}.

Updating Existing Gists

When updating a gist that was previously shared:

1. Edit the gist with gh gist edit {id}
2. POST to the refresh endpoint to bust stale cache. There is a 1-minute cooldown between purge requests:

   curl -s -X POST https://gists.sh/{user}/{id}/refresh
   

3. Warm the cache with the updated content:

   curl -s https://gists.sh/{user}/{id} > /dev/null
   

Display Parameters

Only suggest these when the user explicitly requests a specific display style. Default URLs with no params are preferred.

• ?theme=dark / ?theme=light -- force dark or light mode
• ?noheader -- hide title, tabs, and copy buttons
• ?nofooter -- hide author info and footer
• ?mono -- monospace font for all text
• ?file={filename} -- show a specific file from multi-file gists

Parameters are composable: gists.sh/{user}/{id}?theme=dark&noheader&nofooter