playbooks

home / skills / lecion / github-kb / github-kb

github-kb skill

/SKILL.md

This skill helps you explore and understand GitHub open source projects by cloning repos, analyzing code, and maintaining a CLAUDE.md index.

npx playbooks add skill lecion/github-kb --skill github-kb

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.4 KB
---
name: github-kb
description: Explore, research, and learn GitHub open source projects. Use when users want to understand implementation details, technical solutions, or track trending repositories. Clone repos and analyze source code based on user questions. Manage a local knowledge base with CLAUDE.md index.
---

# GitHub Knowledge Base Explorer

## Installation

Add via Claude Code plugin marketplace:

```bash
/plugin marketplace add lecion/github-kb
```

## Configuration

Set the `GITHUB_KB_ROOT` environment variable to customize the working directory.

## Working Directory

Dynamic path based on `GITHUB_KB_ROOT` environment variable (default: `~/github-kb/`).

## Knowledge Base Management

### CLAUDE.md Location

The knowledge base index is located at `{GITHUB_KB_ROOT}/CLAUDE.md`. This file indexes all explored repositories.

### CLAUDE.md Format

```markdown
# Claude Code 知识库

本目录包含 X 个 GitHub 项目，涵盖...领域描述

---

## Category Name

### [project-name](/project-name)
Brief description of the project
```

### Updating CLAUDE.md

When cloning or exploring a new repository, update CLAUDE.md to maintain consistency:

- Add the project under an appropriate category
- Include project name (linked to its directory) and brief description
- Update the project count in the header

## Workflow

### 1. Knowledge Base Lookup (First Step)

When user asks about a repository:

1. Read `{GITHUB_KB_ROOT}/CLAUDE.md` to check if the project exists
2. If found, explore the existing directory using Read, Glob, and Grep tools
3. If not found, proceed to clone

### 2. Cloning New Repositories

When user wants to explore a new repo or the repo doesn't exist:

```bash
cd {GITHUB_KB_ROOT}
git clone <repo-url>
```

- Use HTTPS or SSH based on repo accessibility
- Default clone directory is always `{GITHUB_KB_ROOT}`

### 3. Exploring and Analyzing

After cloning or when working with existing repos:

- Use the Task tool with Explore agent for comprehensive code analysis
- Use Glob/Read/Grep for targeted on: architecture, exploration
- Focus implementation details, technical decisions, key files

### 4. Maintaining the Knowledge Base

After successful exploration:

- Update CLAUDE.md with new project entry
- Include accurate category and description
- Ensure links and formatting are correct

## Categories for CLAUDE.md

Common categories for organizing projects:

- **Web Frameworks** - Frontend/backend frameworks
- **DevOps Tools** - CI/CD, deployment, infrastructure
- **Machine Learning** - ML libraries, models, tools
- **Mobile Development** - iOS, Android, cross-platform
- **Utilities** - CLI tools, productivity
- **Databases** - Database clients, ORMs
- **APIs & Services** - API clients, SDKs
- **Other** - Projects that don't fit other categories

## Environment Variables

| Variable        | Description                | Default        |
|-----------------|----------------------------|----------------|
| `GITHUB_KB_ROOT` | Root directory for clones  | `~/github-kb/` |

## Examples

```markdown
# Clone a new repository
cd $GITHUB_KB_ROOT
git clone https://github.com/example/repo.git

# Explore an existing repository
Task tool -> Explore agent -> analyze repo structure

# Update knowledge base
Edit CLAUDE.md -> add new project entry
```

## Backward Compatibility

Existing users don't need any configuration changes. The default path maintains backward compatibility.

Overview

This skill helps you explore, research, and learn from GitHub open source projects by cloning repos, analyzing source code, and maintaining a local indexed knowledge base. It streamlines repository lookups, targeted code inspection, and documentation of findings in a central CLAUDE.md index. Use it to understand implementation details, track technical decisions, and keep a searchable archive of explored projects.

How this skill works

First it checks a local knowledge base index (CLAUDE.md) to see if a repository has already been cloned and summarized. If the project exists, it inspects the local copy with targeted tools (read, glob, grep) and an Explore agent to extract architecture and implementation details. If the repo is new, it clones into a configurable root directory, performs automated or guided analysis, and updates the CLAUDE.md index with a categorized entry and brief description.

When to use it

  • You want a quick project-level overview or implementation walkthrough for a GitHub repo.
  • You need to trace where a feature or bug is implemented across source files.
  • You want to build or maintain a local indexed archive of explored open-source projects.
  • You need to compare architectural decisions across similar projects.
  • You want to prepare documentation or technical notes after a repo review.

Best practices

  • Set GITHUB_KB_ROOT to a predictable directory so all clones and the index stay organized.
  • Always check CLAUDE.md first to avoid duplicate clones and to leverage existing summaries.
  • When cloning, use HTTPS or SSH according to repo access and update the index immediately after exploration.
  • Use targeted searches (glob/grep) for specific implementation questions before doing full analysis to save time.
  • Categorize new entries clearly and write a concise one-line description to make future lookups faster.

Example use cases

  • Investigate how an open-source web framework implements routing and middleware across modules.
  • Clone a promising ML library and extract key model classes, configuration patterns, and training loops for comparison.
  • Track trending repos in a domain by cloning and summarizing them into CLAUDE.md for team knowledge sharing.
  • Answer developer questions about where a function is defined and how data flows across the codebase.
  • Create a curated local catalog of useful CLI tools and utilities with short descriptions and category tags.

FAQ

Where is the local knowledge base stored?

The index lives at GITHUB_KB_ROOT/CLAUDE.md (default ~/github-kb/). Change the GITHUB_KB_ROOT environment variable to relocate it.

How do I add a newly analyzed repo to the index?

After cloning and exploring, edit CLAUDE.md: add the project under the appropriate category, include a linked directory name, a brief description, and update the total project count in the header.