Github Knowledge Base

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)

1. 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
2. Smart PDF Summarization - Create structured summaries that save 80-90% tokens on repeated reads
3. 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 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
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 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
3. Analyze structure: kb_explore.py analyze
4. Show README: kb_explore.py readme
5. Find key files: kb_explore.py entry-points and kb_explore.py docs

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 wants to search their KB:

1. Use kb_search.py code with appropriate filters
2. Show code snippets from matching repositories
3. Provide context about which repos matched and why

Example:

User: "What repos in my KB handle error handling? Show me examples"

Steps:
1. Run: python kb_search.py code "error|Error|handleError" --tag backend
2. Present the code snippets with file paths
3. Summarize the different approaches found

When the user wants to compare implementations:

1. Ensure both repos are cloned
2. Use kb_search.py compare
3. Analyze and explain the differences

Example:

User: "Compare how Express and Fastify handle middleware"

Steps:
1. Check if both are in KB and cloned
2. Run: python kb_search.py compare express fastify "middleware"
3. Show code from both repos
4. Explain the architectural differences

When the user wants to see their collection:

1. Use kb.py list with appropriate filters
2. Show the organized list
3. Offer to explore specific repos or categories

Example:

User: "Show me all my frontend repos"

Steps:
1. Run: python kb.py list --tag frontend
2. Display the results
3. Ask: "Would you like to explore any of these in detail?"

When the user wants to track changes or updates:

1. Use kb_changes.py latest to show recent releases and commits
2. Add --detailed for automatic change analysis (breaking changes, API changes, etc.)
3. Use kb_changes.py api-changes to detect property renames and API modifications
4. Use kb_changes.py watch to track repositories for future updates

Example:

User: "What's new in React?"

Steps:
1. Run: kb-changes latest facebook/react --detailed
2. Show the latest release with analysis
3. Highlight breaking changes, new features, and API changes
4. Note any naming convention changes (e.g., camelCase to snake_case)

Example:

User: "Has the API changed in version 18?"

Steps:
1. Run: python kb_changes.py compare facebook/react v17.0.0 v18.0.0
2. Run: python kb_changes.py api-changes facebook/react
3. Show detected API changes including property renames
4. Explain the impact of changes

Example:

User: "Keep me updated on Next.js changes"

Steps:
1. Run: python kb_changes.py watch vercel/next.js
2. Confirm watching
3. Later: python kb_changes.py updates
4. Show any new releases or commits

Best Practices for Claude

1. Be conversational - Don't just run commands, explain what you're doing and why
2. Be helpful - Suggest next steps and related actions
3. Be efficient - Run multiple commands in sequence when it makes sense
4. Handle errors gracefully - If a repo isn't cloned, offer to clone it
5. Suggest organization - Recommend tags, status updates, and notes
6. Make connections - Point out related repos and patterns
7. Educate - Explain what you find in the repositories

GitHub API Rate Limits

• Without token: 60 requests/hour
• With GITHUB_TOKEN: 5000 requests/hour

If rate limited, inform the user and suggest setting GITHUB_TOKEN:

export GITHUB_TOKEN=your_github_token_here

Common User Intents and Responses

| User Says | What to Do | |-----------|-----------| | "Add [repo] to my KB" | kb.py add, then suggest related repos | | "Find repos for [topic]" | kb_search.py github with appropriate filters | | "What's in my KB?" | kb.py list or kb.py stats | | "Explore [repo]" | Clone (if needed), analyze, show structure | | "How does [repo] handle [topic]?" | Clone (if needed), search code for topic | | "Compare [repo1] and [repo2]" | Ensure both cloned, use compare command | | "Search my repos for [pattern]" | kb_search.py code | | "What else should I add?" | Suggest based on existing repos and their tags | | "Show my [tag] repos" | kb.py list --tag | | "What's new in [repo]?" | kb_changes.py latest with detailed analysis | | "Has [repo] been updated?" | kb_changes.py updates or check latest changes | | "What changed in version X?" | kb_changes.py compare between versions | | "Show me breaking changes" | kb_changes.py latest --detailed, highlight breaking changes | | "Track API changes" | kb_changes.py api-changes to detect renames and modifications | | "Watch [repo] for updates" | kb_changes.py watch to track future changes |

Error Handling

• If KB not initialized: Scripts will auto-initialize on first use
• If repo not in KB: Suggest adding it first
• If repo not cloned: Offer to clone it
• If API rate limited: Suggest using GITHUB_TOKEN
• If command fails: Explain the error and suggest fixes

Tips for Effective Use

1. Start with discovery - Search GitHub first, then add interesting repos
2. Tag consistently - Use tags like "frontend", "backend", "database", "auth", etc.
3. Clone selectively - Only clone repos you want to explore deeply
4. Use shallow clones - For large repos, use --depth 1 to save space
5. Keep notes - Add context about why you added a repo and what you learned
6. Track status - Update status as you progress through exploration
7. Compare similar repos - Learn different approaches to the same problems

Example Conversations

Example 1: Adding and Exploring

User: Add the Next.js repo
Claude: [Runs kb.py add vercel/next.js]
        Added Next.js! It's a React framework with 120k+ stars.
        Related repos you might want to add: remix-run/remix, gatsbyjs/gatsby
        Want me to clone and explore it?

User: Yes, explore it
Claude: [Runs kb_explore.py clone vercel/next.js]
        [Runs kb_explore.py analyze vercel/next.js]
        Next.js has a well-organized monorepo structure...
        [Explains the architecture]
        I've set the status to 'exploring'. Want me to find the entry points?

Example 2: Research and Discovery

User: I need to implement auth in my Node.js app. Find me some good auth libraries.
Claude: [Runs kb_search.py github "nodejs authentication" --stars ">2000"]
        Found several excellent auth libraries:
        1. passport (23k stars) - Simple authentication middleware
        2. jsonwebtoken (17k stars) - JWT implementation
        3. bcrypt (6k stars) - Password hashing
        Would you like to add any of these to your KB?

User: Add passport
Claude: [Runs kb.py add jaredhanson/passport]
        [Runs kb_search.py related jaredhanson/passport]
        Added passport! Also found 200+ passport strategy plugins.
        Popular ones: passport-local, passport-google-oauth20, passport-jwt
        Want to add any of these?

Example 3: Code Search and Comparison

User: How do frameworks handle middleware? Search my KB
Claude: [Runs kb_search.py code "middleware|use\(" --tag backend]
        Found middleware implementations in 4 repos:

        Express: Uses .use() method with simple function composition
        Fastify: Uses plugin system with encapsulation
        Koa: Uses async/await with context object

        [Shows code snippets]

        Each has a different approach. Want me to do a detailed comparison?

User: Compare Express and Fastify
Claude: [Runs kb_search.py compare express fastify "middleware"]
        [Shows side-by-side code]

        Key differences:
        - Express: Synchronous by default, error handling via next()
        - Fastify: Async-first, uses plugin encapsulation
        - Fastify is generally faster due to schema-based validation

Example 4: Adding PDFs with Smart Detection

User: I downloaded the Clean Code PDF. Can I add it to my knowledge base?
Claude: Let me check if that's a known book first...
        [Runs kb_books.py check "Clean Code"]

        ⚠️  TOKEN ALERT!

        Clean Code by Robert C. Martin is already in my training data!
        Adding the PDF would waste ~45,000 tokens.

        Instead, you can ask me directly:
        - "Summarize the main principles from Clean Code by Robert Martin"
        - "Review this code using Clean Code principles"
        - "Explain the naming conventions from Clean Code"

        Want to se

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [evelyn9410](https://github.com/evelyn9410)
- **Source:** [evelyn9410/github-knowledge-base](https://github.com/evelyn9410/github-knowledge-base)
- **License:** MIT

Install and usage instructions live in the source repository linked above.