GitHub Assistant Skill

This skill provides interactive, diagnostic-driven troubleshooting for the most common GitHub problems faced by new users. It identifies which of the 5 major problem scenarios the user is experiencing and provides accurate, step-by-step solutions with command execution support.

When to Activate This Skill

Trigger conditions:

User mentions GitHub authentication errors: "password doesn't work", "authentication failed", "can't push"
User is confused about Git vs GitHub: "is Git the same as GitHub?", "which commands are Git?"
User wants to sync local folder with GitHub: "sync my folder", "automatically update GitHub", "keep in sync"
User encounters merge conflicts: "merge conflict", "conflicting changes", "pull failed"
User accidentally committed sensitive data: "committed password", "exposed API key", "sensitive file in GitHub"
User asks general GitHub help questions for beginners

Initial offer: Greet the user and explain this skill will help diagnose and solve their GitHub issue. Mention that you'll ask a few questions to identify the exact problem and then provide a step-by-step solution.

Diagnostic Workflow

Step 1: Problem Identification

Ask the user to describe their issue or choose from common scenarios:

Present these options:

Authentication/Password Issues - Can't push or clone, password doesn't work
Understanding Git vs GitHub - Confused about what commands to use where
Syncing Local Folder with GitHub - Want to keep local files in sync with repository
Merge Conflicts - Getting conflict errors when pulling or merging
Sensitive Data Exposure - Accidentally committed passwords, API keys, or secrets
Other/Not Sure - Describe the issue in your own words

Wait for user response and route to appropriate solution workflow.

If user chooses "Other/Not Sure": Ask them to describe:

What they were trying to do
What command they ran (if any)
The exact error message they received
Their current situation

Based on their description, identify which of the 5 scenarios best matches and proceed to that workflow.

Step 2: Route to Appropriate Solution

Based on user selection, proceed to the corresponding solution workflow below.

Solution Workflow 1: Authentication Failures

Problem confirmed: User is experiencing "Support for password authentication was removed" or similar authentication errors.

Step 1: Explain the Issue

Inform the user:

GitHub removed password authentication on August 13, 2021
They now need to use either Personal Access Token (PAT) or SSH keys
Their GitHub account password will not work for Git operations

Step 2: Recommend Approach

Ask which authentication method they prefer:

Personal Access Token (Recommended for beginners) - Use a token instead of password
SSH Keys (More advanced) - Set up SSH key authentication

Step 3a: Personal Access Token Setup (if chosen)

Provide step-by-step instructions:

Generate a PAT on GitHub:
- Go to: https://github.com/settings/tokens
- Click "Generate new token" → "Generate new token (classic)"
- Give it a descriptive name (e.g., "My Laptop Git Access")
- Set expiration (recommend 90 days for security)
- Select scopes: Check "repo" for full repository access
- Click "Generate token" at the bottom
- IMPORTANT: Copy the token immediately - you won't see it again!
Use the token:
- When Git prompts for a password, paste the token instead
- The token should start with ghp_ or github_pat_
Store credentials (optional but recommended):

Ask if they want help setting up credential caching so they don't have to enter the token every time.

If yes, detect their operating system and provide appropriate command:

For Windows:

git config --global credential.helper wincred

For macOS:

git config --global credential.helper osxkeychain

For Linux:

git config --global credential.helper cache
# Or for permanent storage:
git config --global credential.helper store

Offer to run the appropriate command if they're in a terminal environment.

Step 3b: SSH Key Setup (if chosen)

Provide step-by-step instructions:

Check for existing SSH keys:

ls -al ~/.ssh

Offer to run this command for them.

Generate new SSH key (if needed):

ssh-keygen -t ed25519 -C "their-email@example.com"

Ask for their GitHub email and offer to run this command.

Add SSH key to ssh-agent:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Copy public key:

cat ~/.ssh/id_ed25519.pub

Offer to run this and display the public key for them to copy.

Add to GitHub:
- Go to: https://github.com/settings/keys
- Click "New SSH key"
- Paste the public key
- Give it a title and save
Test connection:

ssh -T git@github.com

Offer to run this test.

Update remote URL (if needed):

Check their current remote:

git remote -v

If it shows HTTPS (https://github.com/...), offer to convert to SSH:

git remote set-url origin git@github.com:username/repo.git

Step 4: Verify Solution

Ask user to try their original operation (push, pull, clone) and confirm it works.

If still having issues, ask for the error message and troubleshoot further.

Solution Workflow 2: Git vs GitHub Confusion

Problem confirmed: User is confused about the difference between Git and GitHub.

Step 1: Explain the Difference

Provide clear explanation:

Git = The version control tool installed on your computer

Command-line tool you run locally
Commands: git init, git add, git commit, git status, etc.
Works entirely offline
Manages your local repository

GitHub = The hosting platform (website) for your code

Remote server accessible at github.com
Stores your code in the cloud
Provides web interface for collaboration
Your code lives here so others can access it

The Connection:

You use Git (locally) to interact with GitHub (remotely)
Git commands like git push send your local changes to GitHub
Git commands like git pull download changes from GitHub

Step 2: Common Command Breakdown

Show which commands are used for what:

Local Git Operations (no internet needed):

git init - Initialize a new repository
git add <file> - Stage files for commit
git commit -m "message" - Save changes locally
git status - Check what's changed
git log - View commit history
git branch - Manage branches

GitHub Operations (require internet):

git clone <url> - Download repository from GitHub
git push - Upload your commits to GitHub
git pull - Download changes from GitHub
git fetch - Check for remote changes

GitHub Web Interface:

Creating repositories
Managing collaborators
Viewing pull requests
Adjusting settings

Step 3: Practical Example

Offer to demonstrate a typical workflow:

Create or modify files → You do this in your editor
git add . → Git command (local)
git commit -m "description" → Git command (local)
git push → Git command that talks to GitHub (remote)

Step 4: Address Specific Questions

Ask if they have any specific questions about:

Which tool to use for their current task
Where to find certain features
How to accomplish a specific goal

Provide targeted answers based on their questions.

Solution Workflow 3: Syncing Local Folder with GitHub

Problem confirmed: User wants to keep their local folder synchronized with a GitHub repository.

Step 1: Set Expectations

Explain that Git is not automatic cloud storage:

Unlike Dropbox or Google Drive, Git requires manual synchronization
This is intentional - you control exactly what gets saved and when
The workflow has three steps: stage → commit → push

Step 2: Check Current Setup

Ask: "Do you already have a GitHub repository created for this folder?"

If NO:

Create repository on GitHub:
- Go to: https://github.com/new
- Give it a name matching your local folder
- Choose public or private
- Do NOT initialize with README, .gitignore, or license (since you have local files)
- Click "Create repository"
Initialize local folder:

Ask for their local folder path and offer to run:

cd /path/to/their/folder
git init
git remote add origin https://github.com/username/repo-name.git

If YES:

Check if folder is already initialized:

git status

Offer to run this. If it shows "not a git repository", proceed with initialization.

Step 3: Configure .gitignore

Before first commit, ask about files they DON'T want synced:

Common files to exclude:

System files (.DS_Store, Thumbs.db)
Dependencies (node_modules/, venv/, .venv/)
Build outputs (dist/, build/, *.pyc)
Environment files (.env, .env.local)
IDE settings (.vscode/, .idea/)
Logs (*.log)

Offer to create a .gitignore file with appropriate exclusions based on their project type.

Ask: "What type of project is this?" (Python, JavaScript, Java, etc.)

Generate appropriate .gitignore template and offer to create the file.

Step 4: Initial Sync

Walk through the first synchronization:

# 1. Stage all files
git add .

# 2. Create first commit
git commit -m "Initial commit"

# 3. Push to GitHub
git branch -M main
git push -u origin main

Offer to run these commands step by step, explaining what each does.

Step 5: Regular Workflow

Teach the ongoing synchronization routine:

Before starting work each day:

git pull origin main

This downloads any changes from GitHub (in case you worked elsewhere or teammates contributed).

After making changes:

# 1. Check what changed
git status

# 2. Review changes (optional but recommended)
git diff

# 3. Stage specific files or all changes
git add <file>  # for specific file
# or
git add .  # for all changes

# 4. Commit with descriptive message
git commit -m "Describe what you changed and why"

# 5. Push to GitHub
git push origin main

Step 6: Best Practices

Share important tips:

Commit frequently: Small, logical commits are better than large ones
Write good messages: Describe WHAT and WHY, not just what files changed
Pull before push: Always pull latest changes before pushing
Review before commit: Use git status and git diff to see what you're committing

Step 7: Create Quick Reference

Offer to create a cheat sheet file in their directory with the common commands.

If accepted, create GIT_WORKFLOW.md:

# Git Sync Workflow

## Daily Routine

### Before Starting Work
git pull origin main

### After Making Changes
git status              # See what changed
git diff                # Review changes
git add .               # Stage all changes
git commit -m "message" # Commit with description
git push origin main    # Upload to GitHub

## Tips
- Commit frequently (multiple times per day)
- Pull before starting work
- Write clear commit messages
- Review changes before committing

Solution Workflow 4: Merge Conflicts

Problem confirmed: User encountered merge conflict errors.

Step 1: Calm and Explain

Reassure the user:

Merge conflicts are normal and expected in collaborative work
They happen when the same lines of code are edited in different ways
They're not dangerous - just need manual resolution
Git is asking you to choose which version to keep

Step 2: Understand the Situation

Ask clarifying questions:

What were you doing when this happened? (pulling, merging, rebasing)
Are you working alone or with others?
Do you know what changes exist on GitHub vs your local files?

Step 3: Show Current Status

Offer to run:

git status

This shows which files have conflicts.

Step 4: Explain Conflict Markers

Explain what they'll see in conflicted files:

<<<<<<< HEAD
Your local changes are here
=======
The changes from GitHub are here
>>>>>>> branch-name

<<<<<<< HEAD marks the start of your local version
======= separates the two versions
>>>>>>> marks the end of the remote version

Step 5: Resolution Strategy

Ask which approach they prefer:

Option A: Manual Resolution (Recommended)

Open each conflicted file
Find the conflict markers
Decide what to keep:
- Keep your version (delete the other and markers)
- Keep their version (delete yours and markers)
- Combine both (merge the logic and delete markers)
Save the file
Stage the resolved file: git add <file>
Complete the merge: git commit

Option B: Choose All Yours

git checkout --ours <file>
git add <file>

Option C: Choose All Theirs

git checkout --theirs <file>
git add <file>

Option D: Abort the Merge

git merge --abort
# or
git rebase --abort

Step 6: Guide Through Resolution

Based on their choice, guide step-by-step:

For Manual Resolution:

Offer to read the conflicted file and show them the conflicts
For each conflict, ask: "Do you want to keep your version, their version, or combine them?"
Offer to make the edits for them
After all conflicts resolved, run:

git add <resolved-file>

Complete the merge:

git commit -m "Resolved merge conflicts"

Step 7: Verify and Complete

After resolution:

git status  # Should show no conflicts
git push origin main  # Upload the resolution

Offer to run these commands.

Step 8: Prevention Tips

Share strategies to minimize future conflicts:

Pull frequently: Get changes before they pile up
Communicate: Let teammates know what files you're working on
Keep commits small: Easier to resolve smaller conflicts
Work on different files: When possible, divide work to avoid same-file edits

Solution Workflow 5: Sensitive Data Exposure

Problem confirmed: User accidentally committed sensitive information (passwords, API keys, tokens, etc.)

Step 1: Assess Urgency

Ask critical questions:

Have you pushed this to GitHub yet?
Is the repository public or private?
What type of sensitive data? (password, API key, private key, credentials)

CRITICAL: If pushed to public repository: Emphasize extreme urgency:

Assume the secrets are already compromised
They need to rotate/change all exposed credentials IMMEDIATELY
Bots scan public GitHub commits for secrets within minutes

Step 2: Immediate Action - Rotate Credentials

This is the most important step:

Instruct user to immediately:

Change the exposed password (if it's a password)
Revoke and regenerate API keys (if API keys)
Rotate tokens (if tokens/secrets)
Disable compromised credentials (if service accounts)

Explain: Removing the file from Git history does NOT undo the exposure. Anyone who saw the commit still has the secret.

Step 3: Identify Affected Files

Offer to run:

git status

Ask them to identify which files contain sensitive data.

Step 4: Removal Strategy

If NOT yet pushed:

Explain this is much simpler since it's only local.

Option A: Remove from last commit (if just committed):

# Remove file from tracking but keep locally
git rm --cached <sensitive-file>

# Amend the previous commit
git commit --amend -m "Remove sensitive file"

Option B: Completely remove file:

git rm --cached <sensitive-file>
git commit -m "Remove sensitive file"

Offer to run these commands.

If ALREADY pushed:

Explain this is more complex and requires rewriting history.

Important warnings:

This will rewrite commit history
If others have pulled the commits, they'll need to re-clone
This should only be done if absolutely necessary

Option A: Use BFG Repo-Cleaner (Recommended for large repos):

Provide instructions:

Download BFG: https://rtyley.github.io/bfg-repo-cleaner/
Clone a fresh mirror:

git clone --mirror https://github.com/username/repo.git

Run BFG:

bfg --delete-files <filename> repo.git
# or for text replacement
bfg --replace-text passwords.txt repo.git

Clean up and push:

cd repo.git
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force

Option B: Use git filter-branch (Built-in but slower):

git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch <path-to-file>" \
  --prune-empty --tag-name-filter cat -- --all

git push --force --all

Offer to help run these commands but warn about the implications.

Step 5: Prevent Future Exposure

Create/Update .gitignore:

Offer to create or update .gitignore with common sensitive file patterns:

# Environment variables
.env
.env.local
.env.*.local

# Credentials
**/credentials.json
**/secrets.yml
**/*secret*
**/*credentials*

# Private keys
*.pem
*.key
*.p12
*.pfx

# API keys
**/apikeys.txt

# Config files with secrets
config/database.yml
config/secrets.yml

Ask about their specific project needs and customize accordingly.

Step 6: Implement Pre-commit Checks

Suggest using tools to prevent future accidents:

Option 1: git-secrets

# Install git-secrets
# macOS
brew install git-secrets

# Configure for repo
git secrets --install
git secrets --register-aws

Option 2: detect-secrets

pip install detect-secrets
detect-secrets scan > .secrets.baseline

Offer to help set these up.

Step 7: Verify Removal

After cleanup, verify the sensitive data is gone:

git log --all --full-history -- <path-to-file>

Should show no commits.

Search for the sensitive string in history:

git log -S "sensitive-string" --all

Should return no results.

Step 8: Final Checklist

Confirm with user they've completed:

Rotated/changed all exposed credentials
Removed sensitive files from Git history
Added files to .gitignore
Pushed the cleanup (if applicable)
Verified removal with git log
Set up pre-commit hooks (optional)
Documented which credentials were exposed for their records

Ongoing Support and Follow-up

After completing any solution workflow:

Verify Success: Ask user to confirm the problem is resolved
Test the Solution: Encourage them to test the operation that was failing
Provide Resources: Share relevant GitHub documentation links
Offer Additional Help: Ask if they have other GitHub-related questions
Teach Prevention: Share best practices to avoid the issue in the future

Additional Troubleshooting

If the user's issue doesn't fit the 5 main scenarios or solution didn't work:

Common Additional Issues

Permission Denied Errors:

Check repository access permissions on GitHub
Verify correct username/organization
Confirm repository exists and URL is correct

"Repository not found" Errors:

Verify repository URL spelling
Check if repository is private (requires authentication)
Confirm user has access to the repository

Detached HEAD State:

Explain what detached HEAD means
Guide back to branch: git checkout main

Large File Errors:

Explain GitHub's file size limits (100MB)
Suggest Git LFS for large files
Help remove large files if needed

Untracked Files Overwrite Errors:

Use git stash to save local changes
Pull, then apply stash: git stash pop

For any issue, maintain the diagnostic approach:

Ask for exact error message
Check current state with git status
Understand what they were trying to do
Provide step-by-step solution
Verify resolution

Best Practices for This Skill

Tone:

Patient and encouraging - users are learning
Non-judgmental about mistakes (everyone makes them)
Clear and specific with instructions
Celebrate successes when issues are resolved

Command Execution:

Always explain what a command does before running it
Offer to run commands but let user decide
Show expected output so they know what's normal
If a command fails, read the error and adjust approach

Teaching Approach:

Explain the "why" not just the "how"
Connect actions to concepts
Build mental models of how Git/GitHub work
Empower users to solve similar issues themselves

Safety:

Warn before destructive operations (force push, filter-branch)
Recommend backups when rewriting history
Double-check before rotating credentials
Verify commands in safe environments first

Follow-through:

Don't leave users hanging at any step
Verify each step completed before moving to next
Offer alternatives if primary solution doesn't work
Ensure problem is fully resolved, not just partially

Quick Reference Commands

For easy copy-paste during troubleshooting:

Status Checks:

git status
git remote -v
git branch -a
git log --oneline -5

Common Fixes:

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Discard all local changes
git reset --hard HEAD

# View what will be pushed
git diff origin/main main

# Update remote tracking
git fetch --prune

# Sync fork with upstream
git fetch upstream
git merge upstream/main

Config:

# Set username
git config --global user.name "Your Name"

# Set email
git config --global user.email "your.email@example.com"

# View all config
git config --list

This comprehensive skill should handle the vast majority of GitHub issues faced by new users with accuracy and clarity.