@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/skill-deep-dives/github.md

@@ -0,0 +1,333 @@
+# Skill Deep-Dive: github
+
+**Skill**: `github`
+**Category**: Code/Productivity
+**Setup Difficulty**: 🟢 Easy
+**Time Estimate**: ~2 minutes
+**Platform**: Cross-platform (macOS, Windows, Linux)
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| PR management | View, create, review pull requests | `gh pr list` |
+| Issue management | View, create, comment on issues | `gh issue list` |
+| CI/CD monitoring | Check workflow runs and logs | `gh run list` |
+| Repository operations | Clone, fork, create repos | `gh repo clone owner/repo` |
+| API access | Query GitHub API for custom data | `gh api repos/owner/repo/pulls` |
+| Gist management | Create and manage gists | `gh gist create file.md` |
+| GitHub Releases | Create and manage releases | `gh release create v1.0.0` |
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] `brew` or equivalent package manager — For installing gh CLI
+- [ ] GitHub account — Free account works
+
+### Soft Dependencies (Recommended)
+- None
+
+### This Skill Enables
+- [ ] Code repository management via CLI
+- [ ] CI/CD automation and monitoring
+- [ ] Issue/PR workflow automation
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check for brew (macOS)
+which brew && echo "✅ Homebrew available"
+
+# Or check for apt/yum (Linux)
+which apt && echo "✅ apt available"
+which yum && echo "✅ yum available"
+```
+
+### Installation Steps
+
+```bash
+# macOS
+brew install gh
+
+# Ubuntu/Debian
+sudo apt install gh
+
+# Fedora/RHEL
+sudo dnf install gh
+
+# Windows (via winget)
+winget install --id GitHub.cli
+
+# Verify installation
+gh --version
+```
+
+### Verification
+
+```bash
+# Check gh is accessible
+gh --version
+```
+
+---
+
+## Configuration
+
+### Step 1: Authenticate
+
+```bash
+# Start authentication flow
+gh auth login
+
+# Follow prompts:
+# 1. Choose: GitHub.com
+# 2. Choose: HTTPS (recommended) or SSH
+# 3. Choose: Authenticate with web browser (easiest)
+# 4. Copy the one-time code
+# 5. Press Enter to open browser
+# 6. Paste code and authorize
+
+# Verify authentication
+gh auth status
+```
+
+### Step 2: Test Basic Commands
+
+```bash
+# List your repos
+gh repo list
+
+# List your issues
+gh issue list
+
+# List your PRs
+gh pr list
+```
+
+---
+
+## User Actions Required
+
+1. **Authorize in browser**: Copy one-time code, paste in browser, click "Authorize"
+
+---
+
+## Common Failure Points
+
+### Failure: "Not logged in"
+
+**Symptom**: Commands return "authentication required"
+
+**Cause**: Not authenticated or token expired
+
+**Recovery**:
+```bash
+# Re-authenticate
+gh auth login
+
+# Verify
+gh auth status
+```
+
+**Prevention**: Keep token active, re-auth if expired
+
+---
+
+### Failure: "Repository not found" in non-git directory
+
+**Symptom**: `gh pr list` returns "could not determine repository"
+
+**Cause**: Running gh command outside a git repository without --repo flag
+
+**Recovery**:
+```bash
+# Option 1: Specify repo explicitly
+gh pr list --repo owner/repo
+
+# Option 2: Navigate to git directory
+cd /path/to/your/repo
+gh pr list
+```
+
+**Prevention**: Always use `--repo owner/repo` when outside git directories
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Install gh | ✅ Yes | bash | `brew install gh` |
+| Authenticate | 🟡 Partial | - | Requires browser authorization |
+| List PRs/issues | ✅ Yes | bash | `gh pr list --json` |
+| Check CI status | ✅ Yes | bash | `gh run list` |
+| Create PR | ✅ Yes | bash | `gh pr create` |
+| Merge PR | ✅ Yes | bash | `gh pr merge` |
+
+### Automation Script
+
+```bash
+#!/bin/bash
+# Check CI status for a PR
+
+REPO="$1"
+PR_NUMBER="$2"
+
+if [ -z "$REPO" ] || [ -z "$PR_NUMBER" ]; then
+    echo "Usage: $0 owner/repo PR_NUMBER"
+    exit 1
+fi
+
+echo "Checking CI status for PR #$PR_NUMBER in $REPO..."
+
+# Check PR status
+gh pr checks "$PR_NUMBER" --repo "$REPO"
+
+# Get CI run details
+echo ""
+echo "Recent workflow runs:"
+gh run list --repo "$REPO" --limit 5
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| Check CI from terminal | Show PR status without opening browser | When user mentions PR |
+| Create PR from CLI | Create PR with title, body, reviewers in one command | After code changes |
+| View failed logs | Show exactly which CI step failed | When CI is red |
+| API queries | Custom GitHub queries via JSON output | Advanced workflows |
+
+### Demo Script
+
+```
+Agent: "Let me check the status of your recent pull requests:"
+
+gh pr list --limit 5
+
+Agent: "I can also check CI status for a specific PR:"
+
+gh pr checks 42 --repo owner/repo
+
+Agent: "And if a run failed, I can show you exactly which step broke:"
+
+gh run view <run-id> --log-failed
+
+Agent: "All of this without opening a browser - pure CLI power."
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **cron** | Schedule CI checks | Monitor PR status automatically |
+| **aix** | Index GitHub conversations | Search PR discussions |
+
+---
+
+## Testing Checklist
+
+- [ ] Fresh install: `brew install gh` (or equivalent)
+- [ ] Version check: `gh --version`
+- [ ] Auth works: `gh auth login`
+- [ ] Auth status: `gh auth status`
+- [ ] List repos: `gh repo list`
+- [ ] List PRs: `gh pr list --repo owner/repo`
+- [ ] List issues: `gh issue list --repo owner/repo`
+- [ ] Check runs: `gh run list --repo owner/repo`
+- [ ] View PR: `gh pr view 42 --repo owner/repo`
+- [ ] API query: `gh api repos/owner/repo`
+
+---
+
+## Notes for Onboarding Agent
+
+- **Minimal setup**: Easiest skill to setup (2 minutes)
+- **Universal for developers**: Recommend for anyone who uses GitHub
+- **When NOT to recommend**: User doesn't use GitHub
+- **Value proposition**: "Manage GitHub without leaving the terminal"
+- **Time estimate**: 2 minutes
+- **No prerequisites**: Just needs GitHub account
+
+---
+
+## Common Commands Reference
+
+```bash
+# Pull Requests
+gh pr list                              # List PRs
+gh pr view 42                           # View PR details
+gh pr checks 42                         # Check CI status
+gh pr create                            # Create PR
+gh pr merge 42                          # Merge PR
+
+# Issues
+gh issue list                           # List issues
+gh issue view 123                       # View issue
+gh issue create                         # Create issue
+gh issue close 123                      # Close issue
+
+# CI/CD
+gh run list                             # List workflow runs
+gh run view <run-id>                    # View run details
+gh run view <run-id> --log-failed       # Show failed logs
+
+# Repositories
+gh repo list                            # List your repos
+gh repo clone owner/repo                # Clone repo
+gh repo create                          # Create new repo
+gh repo view owner/repo                 # View repo details
+
+# API
+gh api repos/owner/repo                 # Raw API access
+gh api repos/owner/repo/pulls/42 --jq .title  # With jq filtering
+
+# Gists
+gh gist create file.md                  # Create gist
+gh gist list                            # List gists
+
+# Releases
+gh release list                         # List releases
+gh release create v1.0.0                # Create release
+```
+
+---
+
+## JSON Output
+
+Most commands support `--json` for structured output:
+
+```bash
+# List PRs as JSON
+gh pr list --json number,title,state
+
+# With jq filtering
+gh pr list --json number,title --jq '.[] | "\(.number): \(.title)"'
+
+# Available fields
+gh pr list --json --help  # Shows all available fields
+```
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*