---
name: github-gist-skill-management
description: Manage skills published as GitHub Gists — create, update, auto-update, and handle username changes
version: 1.0.0
gist: https://gist.github.com/gwyntel-git/48b355599b01c0bc5fda9fcecbd4b4c8
source_url: https://gist.githubusercontent.com/gwyntel-git/48b355599b01c0bc5fda9fcecbd4b4c8/raw/github-gist-skill-management.md
---

# GitHub Gist Skill Management

Self-updating skills via GitHub Gists. Handles the common pitfall of gist URLs breaking when GitHub usernames change.

## The Username Change Problem

**Critical:** GitHub gist raw URLs include the username. When you change your GitHub username, all existing gist references break with 404 errors.

**Broken after username change:**
```
https://gist.githubusercontent.com/OLD_USERNAME/GIST_ID/raw
```

**Fixed:**
```
https://gist.githubusercontent.com/NEW_USERNAME/GIST_ID/raw
```

## Creating a Gist Skill

1. **Create the gist:**
```bash
gh gist create skill.md --public -d "Skill description"
# or
curl -X POST https://api.github.com/gists \
  -H "Authorization: token $GITHUB_TOKEN" \
  -d '{"files":{"skill.md":{"content":"..."}},"public":true}'
```

2. **Include self-updating frontmatter:**
```yaml
---
name: my-skill
description: What this skill does
version: 1.0.0
source_url: https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME.md
---
```

3. **Add self-update command in skill:**
```bash
curl -s "https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME.md" > /path/to/skill
```

## Finding Your Gist ID

```bash
# List all your gists
gh gist list

# Get raw URL for a specific gist file
gh api /gists/GIST_ID -q '.files[].raw_url'
```

## After Username Change: Bulk Update All References

When you've changed your GitHub username, you need to update:

1. **The gists themselves** (their internal source_url references)
2. **Local skill files** that reference the gists
3. **Wiki pages** or documentation linking to gists
4. **Any code** with hardcoded gist URLs

### Find all broken references

```bash
# Search skills for old username
grep -r "supermeap123" ~/.hermes/skills/ 2>/dev/null

# Search broader
grep -r "gist.github.com/supermeap123" ~ 2>/dev/null | grep -v ".git"
```

### Update gist content

```bash
# Get current gist content
gh gist view GIST_ID --raw > /tmp/gist.md

# Replace username references
sed -i 's/OLD_USERNAME/NEW_USERNAME/g' /tmp/gist.md

# Push back
gh gist edit GIST_ID /tmp/gist.md
```

### Update local skills

```bash
# Find and replace in all skills
find ~/.hermes/skills -name "SKILL.md" -exec sed -i 's/OLD_USERNAME/NEW_USERNAME/g' {} \;
```

## Gist URL Patterns

| Use case | URL format |
|----------|------------|
| Gist page | `https://gist.github.com/USERNAME/GIST_ID` |
| Raw file (stable) | `https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME.md` |
| Raw latest (no SHA) | `https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/FILENAME.md` |
| With commit SHA | `https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/SHA/FILENAME.md` |

## Testing Raw URLs

Always verify raw URLs work with curl:

```bash
curl -s "https://gist.githubusercontent.com/USERNAME/GIST_ID/raw/skill.md" | head -5
# Should return content, not 404
```

**Debugging 404s:** Get the actual raw URL from GitHub API:

```bash
# Shows exact raw URL including commit SHA
gh api /gists/GIST_ID -q '.files[].raw_url'

# Example output:
# https://gist.githubusercontent.com/gwyntel-git/af775c3d800f9a8914d9ba9bd1576894/raw/a9ab572a1b7f3527ae1469d6b677eb00718b7694/organic-wiki-editor-skill.md
```

If the username in this URL differs from what you're using, you've found the issue.

## Common Pitfalls

- **User mismatch:** Gists created via `gh` CLI use the currently authed user. If you have multiple GitHub accounts, check which one is active: `gh auth status`
- **Secret vs public:** Secret gists still have accessible raw URLs — "secret" just means they're not discoverable via search
- **Filename required:** For gists with multiple files, raw URL needs the filename: `/raw/filename.md`
- **Single file gists:** Can use `/raw` without filename, but including it is more explicit

## Auto-Update Pattern

Skills should include a self-update mechanism. Standard pattern:

```markdown
## Self-Update

Fetch latest before use:
```bash
curl -s "${source_url}" > /path/to/skill.md
```
```

Where `source_url` in frontmatter points to the raw gist URL.

## Migration Checklist (Username Change)

- [ ] Update gist frontmatter source_url to new username
- [ ] Update any self-update commands in gist content
- [ ] Update local skill files in `~/.hermes/skills/`
- [ ] Update any wiki pages referencing the gists
- [ ] Update documentation or README files
- [ ] Test all raw URLs with curl
- [ ] Notify users of the skill if shared externally