github-repo-explore

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

```
┌─────────────────────────────────────────────────────────────────┐
│  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                   │
└─────────────────────────────────────────────────────────────────┘
```

---

## Phase 1: Check Local Cache First

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

### List Cached Repositories

```bash
# List all cached repositories
ls -la .agent_cache/resources/

# List repos by owner
ls -la .agent_cache/resources/microsoft/

# Search for specific repo by name
find .agent_cache/resources -type d -name "*semantic*" 2>/dev/null
```

### Explore Local Repository

If the repository exists locally, use standard file tools:

```bash
# View repository structure
tree -L 2 .agent_cache/resources/microsoft/semantic-kernel/

# Search for patterns in local repo
grep -r "planning" .agent_cache/resources/microsoft/semantic-kernel/python/ --include="*.py" | head -20

# Find specific files
find .agent_cache/resources/microsoft/semantic-kernel -name "*.md" -path "*skills*"
```

---

## Phase 2: GitHub Authentication

From teaglebuilt/skillz, MIT.

More from teaglebuilt/skillz