github-repo-explore | SkillBundle

GitHub Repository Search and Exploration

This skill enables agents to discover, clone, and explore external GitHub repositories when implementing features that may benefit from reference implementations in open-source projects.

When to Use This Skill

Use this skill when you need to:

Find reference implementations for features you're building
Explore how other projects implement similar patterns
Search for code examples across GitHub
Clone external repos for local exploration and learning
Find libraries or tools that could inform your implementation

Do NOT use this skill when:

The task is straightforward and doesn't need external references
The codebase already has established patterns to follow
You're working on proprietary code that shouldn't reference external sources

Resource Directory

All external GitHub repositories MUST be stored in:

.agent_cache/resources/

This is the centralized location for all cloned external repositories. Always check here first before searching GitHub.

Directory Structure

.agent_cache/
└── resources/
    ├── microsoft/
    │   ├── semantic-kernel/
    │   └── TypeChat/
    ├── langchain-ai/
    │   └── langchain/
    └── Significant-Gravitas/
        └── AutoGPT/

Repositories are organized by {owner}/{repo} structure to prevent naming conflicts.

Workflow Overview

Phase 1: Check Local Cache First

Before searching GitHub, always check if a relevant repository is already cloned locally.

List Cached Repositories

Explore Local Repository

If the repository exists locally, use standard file tools:

Phase 2: GitHub Authentication

If you need to search or clone from GitHub, ensure authentication is set up.

Check Authentication Status

Interactive Login (if needed)

This opens a browser for the user to authenticate with their GitHub account.

Verify Login

Phase 3: Search GitHub

Use gh search commands to find relevant repositories or code.

Search for Repositories

Search for Code

View Repository Details

Phase 4: Clone Repository to Cache

When you find a useful repository, clone it to the cache directory.

Clone Commands

Update Existing Clone

Phase 5: Explore Repository

Once cloned, use a combination of gh commands and file reading tools.

Repository Structure Exploration

Code Search in Local Clone

Read Specific Files

After identifying relevant files with grep/find, use the read_file tool to examine content:

Useful gh Commands Reference

Repository Commands

Command	Description
`gh repo view <owner/repo>`	View repo README and details
`gh repo view <owner/repo> --json <fields>`	Get repo metadata as JSON
`gh repo clone <owner/repo> <path>`	Clone repo to specific path
`gh repo list <owner>`	List repos owned by user/org

Search Commands

Command	Description
`gh search repos <query>`	Search for repositories
`gh search code <query>`	Search within code
`gh search issues <query>`	Search issues
`gh search prs <query>`	Search pull requests

Search Filters

Filter	Example	Description
`--language`	`--language python`	Filter by programming language
`--owner`	`--owner microsoft`	Filter by repository owner
`--stars`	`--stars ">1000"`	Filter by star count
`--limit`	`--limit 20`	Limit number of results
`--sort`	`--sort stars`	Sort results (stars, forks, updated)
`--json`	`--json fullName,description`	Output as JSON

JSON Fields for Repos

Common fields for --json output:

fullName - owner/repo
name - repo name only
description - repo description
stargazersCount - number of stars
language - primary language
url - GitHub URL
defaultBranchRef - main branch name

Example Workflows

Example 1: Find Reference Implementations for REST API Patterns

Example 2: Search for Code Patterns

Example 3: Explore Multiple Repos

Best Practices

Always check local cache first -- Avoid redundant cloning
Use shallow clones -- Add -- --depth 1 to save disk space and time
Organize by owner/repo -- Prevents naming conflicts
Use JSON output -- Easier to parse programmatically
Start with grep/find -- Narrow down before reading full files
Respect rate limits -- GitHub has API rate limits; cache results
Clean up periodically -- Remove unused repos from cache

Troubleshooting

Authentication Issues

Rate Limiting

Clone Failures

GitHub Repository Search and Exploration

This skill enables agents to discover, clone, and explore external GitHub repositories when implementing features that may benefit from reference implementations in open-source projects.

When to Use This Skill

Use this skill when you need to:

Find reference implementations for features you're building
Explore how other projects implement similar patterns
Search for code examples across GitHub
Clone external repos for local exploration and learning
Find libraries or tools that could inform your implementation

Do NOT use this skill when:

The task is straightforward and doesn't need external references
The codebase already has established patterns to follow
You're working on proprietary code that shouldn't reference external sources

Resource Directory

All external GitHub repositories MUST be stored in:

.agent_cache/resources/

This is the centralized location for all cloned external repositories. Always check here first before searching GitHub.

Directory Structure

.agent_cache/
└── resources/
    ├── microsoft/
    │   ├── semantic-kernel/
    │   └── TypeChat/
    ├── langchain-ai/
    │   └── langchain/
    └── Significant-Gravitas/
        └── AutoGPT/

Repositories are organized by {owner}/{repo} structure to prevent naming conflicts.

Workflow Overview

Phase 1: Check Local Cache First

Before searching GitHub, always check if a relevant repository is already cloned locally.

List Cached Repositories

Explore Local Repository

If the repository exists locally, use standard file tools:

Phase 2: GitHub Authentication

If you need to search or clone from GitHub, ensure authentication is set up.

Check Authentication Status

Interactive Login (if needed)

This opens a browser for the user to authenticate with their GitHub account.

Verify Login

Phase 3: Search GitHub

Use gh search commands to find relevant repositories or code.

Search for Repositories

Search for Code

View Repository Details

Phase 4: Clone Repository to Cache

When you find a useful repository, clone it to the cache directory.

Clone Commands

Update Existing Clone

Phase 5: Explore Repository

Once cloned, use a combination of gh commands and file reading tools.

Repository Structure Exploration

Code Search in Local Clone

Read Specific Files

After identifying relevant files with grep/find, use the read_file tool to examine content:

Useful gh Commands Reference

Repository Commands

Command	Description
`gh repo view <owner/repo>`	View repo README and details
`gh repo view <owner/repo> --json <fields>`	Get repo metadata as JSON
`gh repo clone <owner/repo> <path>`	Clone repo to specific path
`gh repo list <owner>`	List repos owned by user/org

Search Commands

Command	Description
`gh search repos <query>`	Search for repositories
`gh search code <query>`	Search within code
`gh search issues <query>`	Search issues
`gh search prs <query>`	Search pull requests

Search Filters

Filter	Example	Description
`--language`	`--language python`	Filter by programming language
`--owner`	`--owner microsoft`	Filter by repository owner
`--stars`	`--stars ">1000"`	Filter by star count
`--limit`	`--limit 20`	Limit number of results
`--sort`	`--sort stars`	Sort results (stars, forks, updated)
`--json`	`--json fullName,description`	Output as JSON

JSON Fields for Repos

Common fields for --json output:

fullName - owner/repo
name - repo name only
description - repo description
stargazersCount - number of stars
language - primary language
url - GitHub URL
defaultBranchRef - main branch name

Example Workflows

Example 1: Find Reference Implementations for REST API Patterns

Example 2: Search for Code Patterns

Example 3: Explore Multiple Repos

Best Practices

Always check local cache first -- Avoid redundant cloning
Use shallow clones -- Add -- --depth 1 to save disk space and time
Organize by owner/repo -- Prevents naming conflicts
Use JSON output -- Easier to parse programmatically
Start with grep/find -- Narrow down before reading full files
Respect rate limits -- GitHub has API rate limits; cache results
Clean up periodically -- Remove unused repos from cache

Troubleshooting

Authentication Issues

Rate Limiting

Clone Failures

┌─────────────────────────────────────────────────────────────────┐ │ 1. Check Local Cache (.agent_cache/resources/) │ │ └─ If found → Use local repo for exploration │ └────────────────────────────┬────────────────────────────────────┘ │ Not found ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 2. Authenticate with GitHub (if needed) │ │ └─ gh auth login │ └────────────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 3. Search GitHub for Repositories │ │ └─ gh search repos <query> │ │ └─ gh search code <query> │ └────────────────────────────┬────────────────────────────────────┘ │ Found match ▼ ┌───────────────────────────────────────────────────────────────────┐ │ 4. Clone to Cache Directory │ │ └─ gh repo clone owner/repo .agent_cache/resources/owner/repo │ └────────────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 5. Explore Repository │ │ └─ Use gh commands and file reading tools │ └─────────────────────────────────────────────────────────────────┘