How to Install Codex Skills from Private GitHub Repositories

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, where the script checks for GITHUB_TOKEN or GH_TOKEN environment variables and injects an Authorization: token <TOKEN> header into all HTTP requests.

# 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.

# 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 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:

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 (lines 59-77) parses the URL to extract owner, repository, reference, and path components.

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) 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 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.
• Use 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 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, 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}