home / skills / am-will / codex-skills / read-github

read-github skill

safe

This skill reads GitHub repository docs and code via gitmcp.io, enabling quick understanding and targeted searches for usage and features.

npx playbooks add skill am-will/codex-skills --skill read-github

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

Files (2)

SKILL.md

2.5 KB

---
name: read-github
description: |
  Read and search GitHub repository documentation via gitmcp.io MCP service.

  **WHEN TO USE:**
  - User provides a GitHub URL
  - User mentions a specific repo in owner/repo format
  - User asks "what does this repo do?", "read the docs for X repo", or similar
  - User wants to search code or docs within a repo
---

# Read GitHub Docs

Access GitHub repository documentation and code via the gitmcp.io MCP service.

## URL Conversion

Convert GitHub URLs to gitmcp.io:
- `github.com/owner/repo` → `gitmcp.io/owner/repo`
- `https://github.com/karpathy/llm-council` → `https://gitmcp.io/karpathy/llm-council`

## CLI Usage

The `scripts/gitmcp.py` script provides CLI access to repository docs.

### List Available Tools

```bash
python3 scripts/gitmcp.py list-tools owner/repo
```

### Fetch Documentation

Retrieves the full documentation file (README, docs, etc.):

```bash
python3 scripts/gitmcp.py fetch-docs owner/repo
```

### Search Documentation

Semantic search within repository documentation:

```bash
python3 scripts/gitmcp.py search-docs owner/repo "query"
```

### Search Code

Search code using GitHub Search API (exact match):

```bash
python3 scripts/gitmcp.py search-code owner/repo "function_name"
```

### Fetch Referenced URL

Fetch content from URLs mentioned in documentation:

```bash
python3 scripts/gitmcp.py fetch-url owner/repo "https://example.com/doc"
```

### Direct Tool Call

Call any MCP tool directly:

```bash
python3 scripts/gitmcp.py call owner/repo tool_name '{"arg": "value"}'
```

## Tool Names

Tool names are dynamically prefixed with the repo name (underscored):
- `karpathy/llm-council` → `fetch_llm_council_documentation`
- `facebook/react` → `fetch_react_documentation`
- `my-org/my-repo` → `fetch_my_repo_documentation`

## Available MCP Tools

For any repository, these tools are available:

1. **fetch_{repo}_documentation** - Fetch entire documentation. Call first for general questions.
2. **search_{repo}_documentation** - Semantic search within docs. Use for specific queries.
3. **search_{repo}_code** - Search code via GitHub API (exact match). Returns matching files.
4. **fetch_generic_url_content** - Fetch any URL referenced in docs, respecting robots.txt.

## Workflow

1. When given a GitHub repo, first fetch documentation to understand the project
2. Use search-docs for specific questions about usage or features
3. Use search-code to find implementations or specific functions
4. Use fetch-url to retrieve external references mentioned in docs

Overview

This skill lets you read and search GitHub repository documentation and code using the gitmcp.io MCP service. It converts GitHub repo URLs to gitmcp endpoints and exposes tools to fetch full docs, run semantic doc searches, search code, and fetch external URLs referenced by documentation. Use it to quickly understand a project, find usage examples, or locate implementations inside a repository.

How this skill works

Given a GitHub repository (URL or owner/repo), the skill maps it to a gitmcp.io endpoint and exposes a set of MCP tools named per-repo (e.g., fetch_myrepo_documentation). The workflow is: fetch the repo documentation first, then run semantic searches in docs, use code search for exact matches, and fetch any external URLs cited in the docs. A CLI wrapper (scripts/gitmcp.py) is provided to call these tools directly.

When to use it

You provide a GitHub URL or owner/repo identifier.
You ask “what does this repo do?” or request a summary of a repo’s docs.
You need to search repository documentation for a topic or example.
You want to find where a function or symbol is implemented in the repo’s code.
You need to retrieve an external link referenced from the project docs.

Best practices

Always start by fetching the repository documentation to get high-level context before running specific searches.
Use semantic doc search for conceptual queries and follow up with code search for exact identifiers or implementations.
Provide the repo in owner/repo format or a full GitHub URL to ensure correct gitmcp conversion.
When searching code, use exact function or symbol names for reliable results since code search uses exact-match queries.
If docs reference external resources, use fetch-url to retrieve them instead of copying links manually.

Example use cases

User: “Read the docs for owner/repo” — call fetch_owner_repo_documentation and summarize README and docs.
User: “How do I use X feature?” — run search_owner_repo_documentation "how to use X" and extract examples or snippets.
User: “Where is function foo implemented?” — run search_owner_repo_code "foo" to locate files containing that symbol.
User: “Open the external link in the docs” — use fetch_generic_url_content to retrieve the referenced page.
Developer: batch-check multiple repos with the CLI to index documentation and available MCP tools.

FAQ

Do I need a full GitHub URL or is owner/repo enough?

Either works. The skill converts github.com/owner/repo to gitmcp.io/owner/repo automatically.

Which tool should I call first?

Start with fetch_{repo}_documentation to get the README/docs for context, then use the search tools for detailed questions.

Can code search find partial matches or fuzzy results?

Code search uses exact-match queries via the GitHub Search API; provide the exact identifier for best results.