GitHub Knowledge Base Skill

Build and maintain a personal knowledge base of GitHub repositories for code exploration, learning, and API tracking. Includes smart features for token-efficient code reviews.

Core Capabilities

📚 GitHub Repository Knowledge Base

1. Repository Management - Add, tag, and organize GitHub repositories
2. Discovery - Search GitHub and find related repositories
3. Exploration - Clone and analyze repository structure
4. Code Search - Search for patterns across your knowledge base
5. Comparison - Compare how different repos solve similar problems
6. Change Tracking - Monitor API changes, breaking changes, and releases

🎯 Smart Code Reviews (Token-Optimized)

7. Known Books Detection - Auto-detect popular technical books (Clean Code, Refactoring, etc.) already in Claude's training data to avoid wasting 40,000-60,000 tokens per book
8. Smart PDF Summarization - Create structured summaries that save 80-90% tokens on repeated reads
9. Token Cost Transparency - Every PDF shows estimated token cost before reading

Persistent Storage

All data is stored in ~/.config/github-kb/:

• index.json - Registry of all repositories with metadata
• repos/ - Cloned repositories
• notes/ - Personal notes and PDFs
• notes/pdf_index.json - PDF metadata with token estimates
• notes/*.summary.md - Token-efficient PDF summaries
• cache/ - Cached API responses

Available Commands

Command Shortcuts: Users can optionally install command shortcuts (kb, kb-search, kb-explore, kb-changes) by running ./install-commands.sh. When invoking commands, prefer using the short form if available (e.g., kb add instead of python kb.py add). Both forms work identically.

KB Management (kb / kb.py)

# Add a repository
python kb.py add facebook/react
python kb.py add https://github.com/facebook/react

# List repositories
python kb.py list
python kb.py list --tag frontend
python kb.py list --status explored

# Tag repositories
python kb.py tag facebook/react frontend ui library

# Add notes
python kb.py note facebook/react "Great hooks implementation"

# Set status (bookmarked, exploring, explored, archived)
python kb.py status facebook/react explored

# Get info
python kb.py info facebook/react
python kb.py stats

# Remove repository
python kb.py remove facebook/react

Change Tracking (kb_changes.py)

# Show latest release and commits
python kb_changes.py latest facebook/react
python kb_changes.py latest facebook/react --detailed  # With change analysis

# Show changelog
python kb_changes.py changelog facebook/react

# Track API changes (detects property renames, function changes, etc.)
python kb_changes.py api-changes facebook/react
python kb_changes.py api-changes facebook/react --pattern "*.ts"

# Compare versions
python kb_changes.py compare facebook/react v17.0.0 v18.0.0

# Watch for updates
python kb_changes.py watch facebook/react

# Check all watched repos for updates
python kb_changes.py updates
python kb_changes.py updates facebook/react  # Check specific repo

Search & Discovery (kb_search.py)

# Search GitHub
python kb_search.py github "react state management" --stars ">1000" --language typescript

# Find related repositories
python kb_search.py related facebook/react

# Search code in your KB
python kb_search.py code "useEffect" --tag frontend
python kb_search.py code "handleError" --repo facebook/react

# Compare implementations
python kb_search.py compare facebook/react preactjs/preact "virtual dom"

Repository Exploration (kb_explore.py)

# Clone repository
python kb_explore.py clone facebook/react
python kb_explore.py clone facebook/react --depth 1  # shallow clone

# Sync (pull) repository
python kb_explore.py sync facebook/react

# Analyze structure
python kb_explore.py analyze facebook/react

# Show directory tree
python kb_explore.py tree facebook/react --depth 3

# View README
python kb_explore.py readme facebook/react

# Find documentation
python kb_explore.py docs facebook/react

# Find entry points
python kb_explore.py entry-points facebook/react

# Find tests
python kb_explore.py find-tests facebook/react

PDF Management (kb_pdf.py)

# Add PDF from local file
python kb_pdf.py add ~/Documents/react-internals.pdf --title "React Internals Guide" --tags react architecture

# Add PDF from cloned repository
python kb_pdf.py scan-repo facebook/react  # Find PDFs in repo
python kb_pdf.py add ~/.config/github-kb/repos/facebook__react/docs/Architecture.pdf --source facebook/react

# Remove PDF from knowledge base (original file not affected)
python kb_pdf.py remove react-internals.pdf

# List all PDFs
python kb_pdf.py list
python kb_pdf.py list --tag architecture

# Get PDF info (shows token estimate)
python kb_pdf.py info react-internals.pdf

# Search PDFs by title/tags
python kb_pdf.py search "react"

# Create token-efficient summary
python kb_pdf.py summarize react-internals.pdf

# Tag PDFs for organization
python kb_pdf.py tag react-internals.pdf frontend performance

Known Books Detection (kb_books.py)

Smart Token Management: Automatically detects when PDFs are popular technical books already in Claude's training data, preventing token waste.

# List all known books
python kb_books.py list

# Search for a book
python kb_books.py search "clean code"
python kb_books.py search "refactoring"

# Check if a book is known (before adding PDF)
python kb_books.py check "Clean Code by Robert Martin"

# View curated combinations
python kb_books.py combos

# Show combination details with ready-to-use prompts
python kb_books.py combo clean-code-fundamentals
python kb_books.py combo java-mastery
python kb_books.py combo software-architecture
python kb_books.py combo craftsmanship

Currently Known Books: Clean Code, Refactoring, Design Patterns, Clean Architecture, Effective Java, Effective Python, The Pragmatic Programmer, Domain-Driven Design

Workflow Instructions for Claude

When the user wants to add a repository:

1. Use kb.py add <repo> to add it to the knowledge base
2. Show the summary and metadata returned
3. Suggest related repositories they might want to add using kb_search.py related <repo>
4. Recommend next steps: cloning, tagging, or adding notes

Example:

User: "Add the fastify repo to my knowledge base"

Steps:
1. Run: kb add fastify/fastify
2. Show the repository summary, stars, language
3. Run: kb-search related fastify/fastify --limit 5
4. Suggest: "I've added Fastify. You might also want to add Express, Koa, or Hapi as related frameworks."

When the user wants to find repositories:

1. Use kb_search.py github <query> with appropriate filters
2. Present the results with stars, language, and descriptions
3. Highlight any repos already in their KB
4. Offer to add promising ones

Example:

User: "Find me some good GitHub repos for rate limiting in Node.js"

Steps:
1. Run: kb-search github "rate limiting nodejs" --stars ">500"
2. Present top results with context
3. Ask: "Would you like to add any of these to your knowledge base?"

When the user wants to explore a repository:

1. First check if it's in the KB, if not suggest adding it
2. Clone if not already cloned: kb_explore.py clone <repo>
3. Analyze structure: kb_explore.py analyze <repo>
4. Show README: kb_explore.py readme <repo>
5. Find key files: kb_explore.py entry-points <repo> and kb_explore.py docs <repo>

Example:

User: "Help me understand the architecture of the react repo"

Steps:
1. Check if react is in KB, if not: kb add facebook/react
2. Clone if needed: kb-explore clone facebook/react
3. Run: kb-explore analyze facebook/react
4. Run: kb-explore tree facebook/react --depth 2
5. Run: kb-explore readme facebook/react
6. Explain the structure based on the output
7. Suggest: kb status facebook/react exploring

When the user w