Purpose

Installs skill packages into a local environment or agent client configuration. Handles listing available skills, downloading from registries or GitHub, extraction, integrity verification, client-specific placement, and registration so the skill is discoverable and usable.

When to use this skill

Use when:

• User says "install this skill", "add skill from X", "set up skill", "list skills"
• Installing from a curated registry (e.g.,

  npx skills add skill-name

  )
• Installing from GitHub:

  npx skills add owner/repo

  or

  --url https://github.com/...

• Installing from local tarball, zip, or folder
• Listing available skills from curated or experimental collections
• Linking a local folder for skill development

Do NOT use when:

• Creating or authoring a skill (use

  skill-authoring

  or

  skill-creator

  )
• Packaging a skill for distribution (use

  skill-packaging

  )
• Skill already installed and just needs configuration
• Uninstalling or removing a skill

Operating procedure

Listing available skills

1. Run

   scripts/list-skills.py

   to show curated skills with install status
2. For experimental skills:

   scripts/list-skills.py --path skills/.experimental

3. For JSON output:

   scripts/list-skills.py --format json

4. Present results as numbered list with "(already installed)" annotations
5. Ask user which skills they want installed

Installing from curated registry or GitHub

1. Identify source:
   • Curated:

     scripts/install-skill-from-github.py --repo openai/skills --path skills/.curated/<name>

   • Experimental:

     scripts/install-skill-from-github.py --repo openai/skills --path skills/.experimental/<name>

   • Any GitHub repo:

     scripts/install-skill-from-github.py --repo <owner>/<repo> --path <path/to/skill>

   • By URL:

     scripts/install-skill-from-github.py --url https://github.com/<owner>/<repo>/tree/<ref>/<path>

2. Download: Scripts default to direct download for public repos; fall back to git sparse checkout on auth errors
3. Install: Skills install to

   $CODEX_HOME/skills/<skill-name>

   (default:

   ~/.codex/skills

   )
4. Verify: Confirm folder exists with SKILL.md
5. Report: Tell user "Restart Codex to pick up new skills"

Installing from local source

1. Local folder: Verify SKILL.md exists at path
2. Tarball/zip: Extract to temp, verify contents
3. Verify integrity: Check manifest.yaml if present; verify SHA-256 checksum
4. Copy to target location based on client:
   • Codex:

     $CODEX_HOME/skills/<name>/

   • GitHub Copilot (VS Code):

     .github/skills/<name>/

     or

     .vscode/skills/<name>/

   • Claude Code: project

     .claude/skills/<name>/

     or user

     ~/.claude/skills/<name>/

   • Gemini CLI:

     .gemini/skills/<name>/

5. Register: Update any config files or skill indexes
6. Verify: Skill discoverable by client

Script reference

All scripts require network access — request sandbox escalation when running.

scripts/list-skills.py

scripts/install-skill-from-github.py

Options for install script:

• --repo <owner>/<repo>

  — GitHub repository

• --path <path>

  — Path within repo (multiple allowed)

• --url <url>

  — Full GitHub URL

• --ref <ref>

  — Git ref (default: main)

• --dest <path>

  — Custom install destination

• --method auto|download|git

  — Download method

• --name <name>

  — Override skill name

Output defaults

## Installation Complete

**Skill**: skill-name
**Location**: ~/.codex/skills/skill-name/
**Source**: [registry/GitHub/local]

### Verification
- [x] Files extracted
- [x] SKILL.md present
- [x] Registered

### Next Step
Restart Codex to pick up new skills.
Triggers on: [description summary]

References

• https://developers.openai.com/codex/skills — Codex skill format and installation
• https://docs.github.com/en/copilot/concepts/agents/about-agent-skills — GitHub agent skills
• https://docs.anthropic.com/en/docs/claude-code/overview — Claude Code skill placement
• https://geminicli.com/docs/cli/skills/ — Gemini CLI skills
• Curated skills: https://github.com/openai/skills/tree/main/skills/.curated
• Experimental skills: https://github.com/openai/skills/tree/main/skills/.experimental

Notes

• System skills at https://github.com/openai/skills/tree/main/skills/.system are preinstalled. If asked, explain this. If user insists, download and overwrite.
• Private GitHub repos accessible via git credentials or

  GITHUB_TOKEN

  /

  GH_TOKEN

• Git fallback tries HTTPS first, then SSH
• Installation aborts if destination directory already exists (prevents accidental overwrites)

Failure handling

• Checksum mismatch: Do not install — report "Integrity verification failed, package may be corrupted or tampered with"
• Auth/permission error on download: Fall back to git sparse checkout; if that fails, suggest user set GITHUB_TOKEN
• Destination already exists: Ask user: overwrite, skip, or install as different version?
• Incompatible client: Report which clients are supported, suggest manual placement
• Missing SKILL.md in source: Abort — "Not a valid skill package: no SKILL.md found"
• Network unavailable in sandbox: Request sandbox escalation for network access