alijilani-dev/github-assistant

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:

1. Authentication/Password Issues - Can't push or clone, password doesn't work
2. Understanding Git vs GitHub - Confused about what commands to use where
3. Syncing Local Folder with GitHub - Want to keep local files in sync with repository
4. Merge Conflicts - Getting conflict errors when pulling or merging
5. Sensitive Data Exposure - Accidentally committed passwords, API keys, or secrets
6. 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:

1. 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!

2. Use the token:

   • When Git prompts for a password, paste the token instead
   • The token should start with ghp_ or github_pat_

3. 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:

1. Check for existing SSH keys:

ls -al ~/.ssh

Offer to run this command for them.

2. Generate new SSH key (if needed):

ssh-keygen -t ed25519 -C "[email protected]"

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

3. Add SSH key to ssh-agent:

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

4. Copy public key:

cat ~/.ssh/id_ed25519.pub

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

5. Add to GitHub:

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

6. Test connection:

ssh -T [email protected]

Offer to run this test.

7. 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 [email protected]: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:

1. Create or modify files → You do this in your editor
2. git add . → Git command (local)
3. git commit -m "description" → Git command (local)
4. 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:

1. 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"

2. 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)

1. Open each conflicted file
2. Find the conflict markers
3. 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)
4. Save the file
5. Stage the resolved file: git add <file>
6. 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:

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

git add <resolved-file>

5. 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:

1. Change the exposed password (if it's a password)
2. Revoke and regenerate API keys (if API keys)
3. Rotate tokens (if tokens/secrets)
4. 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:

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

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

3. Run BFG:

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

4. 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:

1. Verify Success: Ask user to confirm the problem is resolved
2. Test the Solution: Encourage them to test the operation that was failing
3. Provide Resources: Share relevant GitHub documentation links
4. Offer Additional Help: Ask if they have other GitHub-related questions
5. 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:

1. Ask for exact error message
2. Check current state with git status
3. Understand what they were trying to do
4. Provide step-by-step solution
5. 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 "[email protected]"

# 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.