# How to Use skill-installer with Private Repositories in Composio Codex

> Easily install skills from private GitHub repos with Composio Codex skill-installer. Learn how automated token detection and SSH fallbacks ensure seamless installation.

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

---

**The skill-installer supports private GitHub repositories by automatically detecting GitHub tokens in environment variables or falling back to SSH-based sparse checkouts when authentication errors occur.**

The `skill-installer` script from the [ComposioHQ/awesome-codex-skills](https://github.com/ComposioHQ/awesome-codex-skills) repository enables developers to install Codex skills from any GitHub repository, including private ones. This guide explains the authentication mechanisms, installation workflow, and security safeguards implemented in the source code.

## Authentication Methods for Private Repositories

The installer implements a **two-step strategy** defined in [`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). It first attempts to download an archive using authenticated HTTPS requests, then falls back to sparse Git checkouts if authentication errors (401/403/404) occur.

### Token-Based Authentication (GITHUB_TOKEN)

The installer automatically authenticates private repositories when you export a GitHub personal access token:

1. Set the environment variable `GITHUB_TOKEN` or `GH_TOKEN` with a token that has `repo` scope
2. The `_download_repo_zip()` function calls `github_utils.github_request`, which injects the token into request headers
3. The script downloads from the GitHub codeload endpoint: `https://codeload.github.com/{owner}/{repo}/zip/{ref}`

```bash

# Export your personal access token

export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Install from a private repository

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

```

### SSH Fallback Authentication

When token-based downloads fail, the installer falls back to `_git_sparse_checkout()`:

- Uses `git clone --filter=blob:none --depth 1 --sparse` to minimize data transfer
- First attempts HTTPS remote, then retries with SSH remote via `_build_repo_ssh()`
- Requires your SSH key to be loaded (`ssh-add`) and authorized for the repository

```bash

# Ensure your SSH key is available

ssh-add ~/.ssh/id_rsa

# Force git method to skip download attempt

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
    --repo MyOrg/private-codex-skills \
    --path my-skills/awesome-skill \
    --method git

```

## Installation Workflow

The installation flow implemented in [`install-skill-from-github.py`](https://github.com/ComposioHQ/awesome-codex-skills/blob/main/install-skill-from-github.py) follows this logic:

1. **Parse arguments** – Accepts `--url` or `--repo` flags, optionally with `--path` and `--ref`
2. **Prepare source** – Validates the repository URL and constructs the source object
3. **Download attempt** – `_download_repo_zip()` tries the codeload endpoint with token authentication
4. **Git fallback** – On HTTP 401/403/404 errors, `_git_sparse_checkout()` clones via SSH
5. **Validate and copy** – `_validate_relative_path()` and `_validate_skill_name()` prevent directory traversal, then `_copy_skill()` installs to `$CODEX_HOME/skills` (defaults to `~/.codex/skills`)

## Step-by-Step Installation Examples

### Install a Single Private Skill Using Token Authentication

```bash

# Set authentication token

export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Install specific path from private repo

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

```

The script extracts the skill to `~/.codex/skills/awesome-skill`.

### Install Multiple Private Skills

When installing multiple paths, the installer uses each path's basename as the skill name:

```bash
export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
    --repo MyOrg/private-codex-skills \
    --path my-skills/skill-a my-skills/skill-b

```

### Install from Full GitHub URL

Instead of using `--repo`, you can pass a complete GitHub URL:

```bash
export GITHUB_TOKEN=ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
    --url https://github.com/MyOrg/private-codex-skills/tree/main/my-skills/awesome-skill

```

The script parses the URL to extract owner, repo, ref, and path components.

## Security Safeguards

The `skill-installer` implements several security validations according to the ComposioHQ source code:

- **Path traversal protection** – `_validate_relative_path()` ensures requested paths cannot escape the repository root
- **Skill name validation** – `_validate_skill_name()` requires names to be single path segments without directory separators
- **Collision prevention** – `_copy_skill()` aborts if the destination directory already exists, preventing accidental overwrites
- **Token isolation** – `github_utils.github_request()` reads tokens from environment only, never from command-line arguments

## Summary

- **skill-installer** accesses private repositories via `GITHUB_TOKEN` or `GH_TOKEN` environment variables injected into codeload requests by `github_utils.github_request()`.
- **Fallback mechanism** automatically switches to SSH sparse checkout (`_git_sparse_checkout()`) when download attempts return 401/403/404 errors.
- **Security** is enforced through path validation functions (`_validate_relative_path`, `_validate_skill_name`) before copying skills to `$CODEX_HOME/skills`.
- **Installation** supports both `--repo` with `--path` flags and full GitHub URLs via `--url`.

## Frequently Asked Questions

### What GitHub token permissions are required for private repositories?

Your personal access token requires the `repo` scope to read private repositories. The installer looks for `GITHUB_TOKEN` or `GH_TOKEN` environment variables and automatically includes them in request headers via `github_utils.github_request()`. Never pass tokens as command-line arguments.

### Why does the installer use sparse checkout instead of cloning the entire repository?

The `_git_sparse_checkout()` function uses `git clone --filter=blob:none --depth 1 --sparse` to download only the specific files needed for the skill, minimizing network usage and disk space. This is particularly efficient for large monorepos containing multiple skills.

### Can I install skills from GitHub Enterprise Server?

The current implementation targets `github.com` endpoints in `_download_repo_zip()` and `_build_repo_ssh()`. For GitHub Enterprise, you would need to modify the base URLs in [`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) or use the `--method git` flag with manually configured Git remotes.

### What happens if a skill with the same name already exists?

The `_copy_skill()` function checks for existing directories in `$CODEX_HOME/skills` and aborts with an error before overwriting. To update an existing skill, you must first remove the old directory manually, then reinstall.