name	claude-thread-publisher
description	Publish Claude Code conversation threads as static HTML pages hosted on GitHub Gists, with shareable gistpreview links. Use when the user asks to share, publish, or delete a Claude Code thread.
allowed-tools	Read, Write, Edit, Bash

Claude Thread Publisher

Publish Claude Code conversation threads as beautiful static HTML pages hosted on GitHub Gists, with shareable permalinks via gistpreview.github.io.

Instructions

When to Use This Skill

Use this skill when the user asks to:

Publish, share, or export a Claude Code conversation
Create a shareable link for the current thread
Delete a previously published thread
Update an existing published thread

High-Level Workflow

Publishing a Thread

When the user wants to publish the current thread:

Check for GitHub Token:
- Look for existing token in ~/.claude/thread-publisher/config.json
- If missing, guide the user to create a GitHub PAT with gist scope
- Store the token locally for future use
Locate Current Session:
- Use session_locator.py to find the current Claude Code session JSONL file
- Handle cases where no session is found gracefully
Generate Content:
- Use render_thread.py to convert JSONL to:
  - Beautiful static HTML (index.html)
  - Normalized thread JSON (thread.json)
  - Metadata (metadata.json)
Publish to Gist:
- Use publish_to_gist.py to create/update GitHub Gist with the three files
- Use secret gists by default for privacy
- Store mapping of thread hash → gist ID in local index
Provide Result:
- Return the gistpreview permalink (e.g., https://gistpreview.github.io/?abcdef1234...)
- Also provide the raw Gist URL for reference
- Include brief confirmation and reminder that the link is live

Deleting a Published Thread

When the user wants to delete a published thread:

Locate Current Thread:
- Use session_locator.py + render_thread.py to compute the current thread's hash
- Look up the thread hash in the local index (~/.claude/thread-publisher/index.json)
Verify and Delete:
- If mapping exists, use delete_gist.py to delete the corresponding GitHub Gist
- Remove the entry from the local index
- Confirm successful deletion to the user
Handle Missing Threads:
- If no mapping exists, inform the user that no published link was found
- Offer to list all published threads if they want to check

Updating a Published Thread

When the user wants to update an existing published thread:

Detect Changes:
- Compute current thread hash and compare with stored version
- If hash differs, the thread has been updated since last publication
Update Strategy:
- By default, update the existing Gist (replace contents)
- This preserves the same permalink URL
- Update the local index with new timestamp
Provide Updated Link:
- Return the same permalink (URL unchanged)
- Confirm that the content has been updated

Script Usage Patterns

Session Location

python scripts/session_locator.py --mode current

Returns JSON with session file path and project information.

Thread Rendering

python scripts/render_thread.py \
  --input /path/to/session.jsonl \
  --output-html /tmp/thread.html \
  --output-json /tmp/thread.json \
  --metadata /tmp/metadata.json \
  --project-path /current/project \
  --session-file /path/to/session.jsonl

Gist Publishing

python scripts/publish_to_gist.py \
  --html /tmp/thread.html \
  --thread-json /tmp/thread.json \
  --metadata /tmp/metadata.json \
  --project-path /current/project \
  --session-file /path/to/session.jsonl

Gist Deletion

python scripts/delete_gist.py \
  --thread-hash <hash>  # or --session-file /path/to/session.jsonl

Key Features

HTML Rendering

Beautiful dark theme optimized for code display
Responsive design that works on mobile and desktop
Syntax highlighting for code blocks
Clear separation between user, assistant, and system messages
One-click "copy link" functionality
Metadata display (thread hash, generation time, message count)

GitHub Integration

Uses GitHub Personal Access Tokens with gist scope only
Creates secret (private) gists by default for privacy
Supports both creation and updates of gists
Maintains local index for tracking published threads
Graceful handling of authentication and API errors

Thread Management

Content-based hashing to detect thread changes
Supports re-publishing updated threads
Comprehensive deletion capabilities
Orphaned gist cleanup functionality

File Structure

claude-thread-publisher/
├── SKILL.md                    # This file
├── examples.md                 # Example prompts
├── scripts/
│   ├── session_locator.py      # Find current Claude Code session
│   ├── render_thread.py        # Convert JSONL to HTML/JSON
│   ├── publish_to_gist.py      # Create/update GitHub Gists
│   └── delete_gist.py          # Delete Gists and manage cleanup
└── templates/                  # (reserved for future HTML templates)

Configuration

The skill stores configuration in ~/.claude/thread-publisher/:

config.json: GitHub token and preferences
index.json: Mapping of thread hashes to Gist IDs

Example Configuration

{
  "github_token": "ghp_xxxxxxxxxxxxxxxxxxxx",
  "gists_private_by_default": true
}

Example Index Entry

{
  "threads": {
    "a1b2c3d4e5f6...": {
      "gist_id": "abcdef1234567890...",
      "gist_url": "https://gist.github.com/abcdef1234567890...",
      "last_published_at": "2024-01-01T12:00:00Z",
      "project_path": "/home/user/my-project",
      "session_file": "/home/user/.claude/projects/abc/sessions/def.jsonl",
      "title": "Implement user authentication feature"
    }
  }
}

Security and Privacy

Local Token Storage: GitHub PAT is stored locally on user's machine only
Gist Privacy: Creates secret (private) gists by default
Content Control: Only publishes the specific thread content user requests
No External Services: Relies only on GitHub's official Gist API
Token Scope: Requires only gist scope (minimal permission)

Error Handling

Missing Session: Gracefully handles cases where no current session can be found
Authentication Issues: Guides users through PAT setup when missing
API Failures: Provides clear error messages for GitHub API issues
File I/O Errors: Handles file permission and path issues gracefully
Network Issues: Implements timeouts and retry logic where appropriate

Troubleshooting

Common Issues

"No session file found"
- User may be in a directory without a Claude Code project
- Check if ~/.claude/projects/ exists and contains relevant project
- Try explicitly specifying session file path
"GitHub token required"
- User needs to create a PAT at github.com/settings/tokens
- Token must have gist scope
- Token will be stored locally after first use
"Gist creation failed"
- Check GitHub API status
- Verify token has correct permissions
- Check network connectivity
"Thread hash mismatch"
- Thread content has changed since last publication
- This is normal when updating threads
- Skill will handle updating the gist

Examples

Basic Publishing

"Publish this Claude Code conversation as a shareable link."

Updating

"Update the published link for this thread with the new messages."

Deleting

"Delete the public link you created for this conversation."

Listing

"Show me all the threads I've published."

Dependencies

Python 3.7+
requests library for HTTP requests
Standard library modules: json, pathlib, datetime, argparse, hashlib

Best Practices

Always confirm with user before deleting published content
Use descriptive thread titles based on first user message
Keep gists private by default to respect user privacy
Provide both gistpreview permalink and direct gist URL
Maintain local index for thread management
Handle API errors gracefully with user-friendly messages

Install Skill

SKILL.md