# How to Install Codex Skills from Private GitHub Repositories

> Install Codex skills from private GitHub repos securely. Use the Skill Installer utility with a GITHUB_TOKEN for seamless authentication via ZIP or sparse-checkout. Export your token now.

- Repository: [Composio/awesome-codex-skills](https://github.com/composiohq/awesome-codex-skills)
- Tags: how-to-guide
- Published: 2026-04-26

---

**You can install Codex skills from private GitHub repositories by exporting a `GITHUB_TOKEN` environment variable and using the Skill Installer utility from the Awesome Codex Skills collection, which automatically handles authentication via ZIP download or Git sparse-checkout.**

The Awesome Codex Skills repository (`ComposioHQ/awesome-codex-skills`) includes a Skill Installer utility that enables you to fetch skills from any GitHub repository—public or private. This tool supports authenticated access to private repositories using personal access tokens, allowing teams to maintain proprietary skill libraries while leveraging the same installation workflow as public skills.

## Authentication Requirements for Private Repositories

To access private repositories, the installer requires a GitHub personal access token with appropriate repository permissions. The authentication logic resides in [`skill-installer/scripts/github_utils.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/skill-installer/scripts/github_utils.py), where the script checks for `GITHUB_TOKEN` or `GH_TOKEN` environment variables and injects an `Authorization: token <TOKEN>` header into all HTTP requests.

```python

# github_utils.py – line 10-15

headers = {"User-Agent": user_agent}
token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
if token:
    headers["Authorization"] = f"token {token}"

```

This token enables both ZIP archive downloads via `codeload.github.com` and GitHub API calls that list repository contents. Without this token, the installer cannot access private repository data.

## Installation Methods and Auto-Detection

The Skill Installer operates in two distinct modes, automatically selecting the most appropriate method via `--method auto`:

- **Download mode (default)**: Fetches a ZIP archive via HTTPS and extracts only the requested path. This works for private repos when the `GITHUB_TOKEN` is present in the environment.
- **Git mode**: Performs a sparse checkout using `git clone --filter=blob:none --depth 1`. This is optimal for very large repositories or when using SSH-based authentication.

If the ZIP download fails—typically due to missing authentication—the installer automatically falls back to the Git method.

## Installing Skills from Private Repositories

### Method 1: ZIP Download (Default)

For most private repositories, the default ZIP download method is fastest. You must specify the `--path` argument because the installer cannotguess skill locations in private repos without API access.

```bash

# Export a personal access token with 'repo' scope

export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Install the skill

python skill-installer/scripts/install-skill-from-github.py \
    --repo MyOrg/private-codex-skills \
    --path my-private-skill \
    --ref main

```

The installer executes the following steps:
1. Downloads the ZIP from `https://codeload.github.com/MyOrg/private-codex-skills/zip/main` using the authentication header.
2. Extracts only the `my-private-skill` directory using the `_safe_extract_zip` function.
3. Validates the presence of a [`SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/SKILL.md) file.
4. Copies the skill to `$CODEX_HOME/skills/my-private-skill`.

### Method 2: Git Sparse-Checkout

For large private repositories where you want to minimize download size, force the Git method to perform a sparse checkout:

```bash
export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
python skill-installer/scripts/install-skill-from-github.py \
    --repo MyOrg/private-codex-skills \
    --path my-private-skill \
    --method git

```

This command clones with `--filter=blob:none --depth 1`, fetching only the specific skill directory rather than the entire repository history.

### Method 3: Using Full GitHub URLs

You can also provide a complete GitHub URL instead of separate `--repo` and `--path` arguments. The `_parse_github_url` function in [`install-skill-from-github.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/install-skill-from-github.py) (lines 59-77) parses the URL to extract owner, repository, reference, and path components.

```bash
python skill-installer/scripts/install-skill-from-github.py \
    --url https://github.com/MyOrg/private-codex-skills/tree/main/my-private-skill \
    --method auto

```

## Security Validation and Safety Checks

The installer implements several safety mechanisms to protect your system:

- **Path traversal protection**: The `_safe_extract_zip` function (lines 5-13 in [`install-skill-from-github.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/install-skill-from-github.py)) validates that no file inside the ZIP archive escapes the temporary destination directory, preventing malicious archive attacks.
- **Destination validation**: Before copying, the script verifies that the target skill name is a single path segment and that `$CODEX_HOME/skills/<skill-name>` does not already exist (lines 20-26).
- **Structure verification**: Every installed skill must contain a [`SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/SKILL.md) file at its root; otherwise, the installation aborts.

## Summary

- Export `GITHUB_TOKEN` or `GH_TOKEN` to enable private repository access through [`skill-installer/scripts/github_utils.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/skill-installer/scripts/github_utils.py).
- Use [`skill-installer/scripts/install-skill-from-github.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/skill-installer/scripts/install-skill-from-github.py) with mandatory `--repo` and `--path` flags for private installations.
- The installer automatically selects between ZIP download and Git sparse-checkout based on availability and repository size.
- Built-in security checks prevent archive path traversal and accidental directory overwrites.
- All skills must contain a [`SKILL.md`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/SKILL.md) file to pass validation and complete installation.

## Frequently Asked Questions

### What environment variable should I use for GitHub authentication?

Use either `GITHUB_TOKEN` or `GH_TOKEN`. According to [`github_utils.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/github_utils.py), the installer checks both environment variables and injects an `Authorization: token <TOKEN>` header for all GitHub API requests and ZIP downloads.

### Why do I need to specify the `--path` argument for private repositories?

Private repositories require explicit path specification because the installer cannot browse repository contents to auto-discover skill directories without authenticated API access. The `--path` flag tells the installer exactly which subdirectory contains the skill.

### How does the installer prevent security risks when extracting archives?

The `_safe_extract_zip` function in [`install-skill-from-github.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/install-skill-from-github.py) (lines 5-13) validates that no extracted file escapes the intended destination directory, protecting against ZIP slip attacks and other path traversal vulnerabilities.

### Can I use SSH authentication instead of tokens for private repos?

Yes. While the ZIP download method requires token-based authentication, you can force the Git method using `--method git`. If your SSH keys are configured, Git will authenticate automatically via SSH rather than HTTPS, bypassing the need for `GITHUB_TOKEN` in Git operations.