Verify gh is available and authenticated:
gh auth status
Handle errors distinctly:
command not found or similar): stop and tell the human “Install the GitHub CLI first: https://cli.github.com”gh is installed but not authenticated: stop and tell the human “Run gh auth login first, then try again.”Do not proceed until this check passes.
Collect everything needed to build the gist — in order of priority:
/create-gist fix.py) — use the file directly; skip temp file creation/create-gist the snippet above --public)Parse the following options from the arguments or conversation:
| Option | Default | Meaning |
|---|---|---|
--public |
off | Make the gist public instead of secret |
--desc <text> |
inferred | Gist description |
--filename <name> |
inferred | Override the filename shown in the gist |
If no content is identifiable, ask the human what to put in the gist before proceeding.
Multi-file gists are out of scope. If multiple files are referenced, ask the human to pick one.
Filename: All gist filenames MUST follow this convention:
{TICKET-ID}-{SUMMARY}.{EXTENSION}
ENG-123, FB-42). If no ticket ID is present, use NO-TICKET.fix-auth-redirect, query-results, migration-output). Max 5 words. No spaces..py, .ts, .sql, .log, .md, etc.). The extension matters — gh uses it for syntax highlighting.If --filename was passed explicitly, use that value verbatim — but still warn the human if it doesn’t match the convention.
Examples of valid filenames:
ENG-123-fix-auth-redirect.pyFB-42-migration-output.logNO-TICKET-query-results.sqlDescription: Summarize the purpose in one short line. Pull from conversation context, the skill args, or the content itself. Keep it under 72 characters.
--public was passed → public gistPresent a summary to the human before creating anything:
File: <filename>
Description: <description>
Visibility: <secret or public>
Content:
---
<first ~20 lines or full content if short>
---
If the content contains secrets (API keys, tokens, passwords, private URLs) — flag them explicitly. Warn the human that even secret gists are accessible to anyone with the URL. Let them decide whether to proceed.
Ask for confirmation. Do not create the gist until the human says yes. If running non-interactively or if the human passed --yes, skip the confirmation prompt.
IMPORTANT — gh gist create’s --filename/-f flag ONLY applies when reading from stdin (-). When you pass a file argument, gh names the gist after that file’s own basename and silently ignores --filename. This means you must NEVER hand gh a randomly-named temp file (e.g. mktemp’s default gist-XXXXXX.ext) — that random name is what ends up as the gist’s filename. Always create the temp file (or copy the source file) under the exact {TICKET-ID}-{SUMMARY}.{EXTENSION} name computed in step 2, then pass that path with no --filename flag needed.
If the source is a file on disk whose name already matches the convention, pass it directly:
# Secret (default)
gh gist create --desc "<description>" <filepath>
# Public
gh gist create --public --desc "<description>" <filepath>
If the source file’s name does NOT match the convention, copy it first to a correctly-named temp path (see below) rather than passing it as-is.
If the source is content from the conversation, or a source file with the wrong name, create a temp directory and write/copy the content into a file with the exact target name:
tmpdir=$(mktemp -d)
tmpfile="$tmpdir/<filename>" # e.g. "$tmpdir/ENG-123-fix-auth-redirect.py"
# write or cp the content into "$tmpfile"
Then run:
# Secret (default)
gh gist create --desc "<description>" "$tmpfile"
# Public
gh gist create --public --desc "<description>" "$tmpfile"
After the gist is created (or if creation fails), delete the temp directory immediately:
rm -rf "$tmpdir"
Return: