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

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

# 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

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

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

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:

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

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