GitHub Gist Skill

Expert management of GitHub Gists via the

gh

README.md

Core Rule: README.md is Mandatory

Every gist must contain a

README.md

README.md

README.md

The README.md must include:

• Description — what the gist does or contains
• Content summary — what files are included and what each does
• Usage (optional, include when the gist contains runnable scripts or commands)

See

references/readme-template.md

Reference Files

references/readme-template.md

references/workflows.md

references/search-and-manage.md

Quick Reference: Common Operations

Create a new gist (single file)

# Always create README.md first, then create gist with both files
cat > /tmp/README.md << 'EOF'
# <gist title>

<description>

## Files

- `<filename>` — <what it does>

## Usage

<usage instructions if applicable>
EOF

gh gist create --public --desc "<description>" /tmp/README.md <your-file>

Create a gist (multiple files)

gh gist create --public --desc "<description>" README.md file1.sh file2.py

List gists

gh gist list                          # 10 most recent
gh gist list -L 50                    # 50 most recent
gh gist list --public                 # only public
gh gist list --secret                 # only secret
gh gist list --filter "pattern"       # filter by description/filename
gh gist list --filter "pattern" --include-content  # search file contents

View a gist

gh gist view <id>                     # rendered view
gh gist view <id> --raw               # raw content
gh gist view <id> --files             # list filenames
gh gist view <id> --filename README.md
gh gist view <id> --web               # open in browser

Edit a gist

gh gist edit <id>                         # interactive (opens editor)
gh gist edit <id> --filename <file>       # edit specific file
gh gist edit <id> --desc "new description"
gh gist edit <id> --add newfile.py        # add a file
gh gist edit <id> --remove oldfile.py     # remove a file

Clone a gist locally

gh gist clone <id> [<directory>]

Delete a gist

gh gist delete <id>

Workflow: Creating a Gist

When a user asks to create a gist, follow these steps:

1. Gather information — determine the description, files involved, and whether it should be public or secret (default: secret)
2. Generate README.md — always write a

   README.md

   using the template in

   references/readme-template.md

3. Assemble files — write the actual script/content files if they don't already exist
4. Create the gist — use

   gh gist create

   with all files, including

   README.md

5. Confirm and report — show the user the gist URL

Always load

references/readme-template.md

Workflow: Adding Files to an Existing Gist

When adding files to a gist:

1. Check if a

   README.md

   exists:

   gh gist view <id> --files

2. If missing, create one with

   gh gist edit <id> --add README.md

3. Add the new file:

   gh gist edit <id> --add <filename>

4. Update the

   README.md

   to document the new file

Determining Visibility

• Secret (default): private to owner, accessible by URL. Use when the content is personal or sensitive.
• Public (

  --public

  ): listed publicly. Use when the intent is sharing with the community.

Ask the user if unclear. Default to secret.

File Naming Convention

• Scripts: use the appropriate extension (

  .sh

  ,

  .py

  ,

  .rb

  ,

  .js

  , etc.)
• Config snippets: use the actual config filename (e.g.,

  .zshrc

  ,

  nginx.conf

  )
• Documentation: always

  README.md

  (never

  readme.txt

  or

  README.txt

  )
• One-liners or reference cards: use

  .md

  format for readability

Error Handling

gh: not authenticated

gh auth login

/tmp/

gh gist list

--limit

Tip: Use

gh gist view <id> --web

to open any gist in the browser for easy sharing.