alijilani-dev/claude/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!

1. Use the token:

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

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

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

1. Add SSH key to ssh-agent:

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

1. Copy public key:

cat ~/.ssh/id_ed25519.pub

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

1. Add to GitHub:

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

1. Test connection:

ssh -T git@github.com

Offer to run this test.

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

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"

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