# Installation

This repository separates Skill development source from the local public installation surface.

## Paths

Development source:

```text
C:\Users\wangq\Documents\Codex\skills-vault
```

Public local Skill installation surface:

```text
C:\Users\wangq\.agents\skills
```

Agent-specific private Skill folders, such as `C:\Users\wangq\.claude\skills`, should link to the public installation surface instead of linking directly to the development source.

## Conda Environment

Use the shared repository environment by default:

```powershell
conda env create -f environment.yml
conda activate skills-vault
```

If the environment already exists:

```powershell
conda activate skills-vault
```

If `conda env create -f environment.yml` fails in Codex or another non-interactive Windows shell because of progress output, solver plugin, or root environment directory issues, create the environment explicitly under the user env directory:

```powershell
C:\Users\wangq\miniconda3\Scripts\conda.exe create -p C:\Users\wangq\.conda\envs\skills-vault python=3.11 pip -y --json --solver classic
```

Then use:

```powershell
conda activate C:\Users\wangq\.conda\envs\skills-vault
```

Most lightweight Skills should use this shared environment. Create a dedicated environment only when a Skill has conflicting or heavy dependencies.

When running Python from automation, prefer `conda run` so the intended environment is explicit even if the shell has not been activated:

```powershell
conda run -n skills-vault python -m unittest discover -s skills\fix-title\tests -v
conda run -n skills-vault python .\skills\fix-title\scripts\fix_markdown_titles.py --help
```

Do not rely on bare `python` unless you have first verified it resolves to `C:\Users\wangq\.conda\envs\skills-vault\python.exe`.

## Install One Skill

PowerShell:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-skill.ps1 -Skill fix-title
powershell -ExecutionPolicy Bypass -File .\scripts\install-skill.ps1 -Skill repair-markdown-citations
```

Git Bash / Linux / macOS:

```bash
bash scripts/install-skill.sh fix-title
```

## Install All Default Skills

PowerShell:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-skill.ps1 -All
```

Git Bash / Linux / macOS:

```bash
bash scripts/install-skill.sh --all
```

Full installation uses `registry/skills-index.md` and installs only Skills with:

```text
Status: tested, installable, or installed
Install Policy: default
```

Conditional, optional, disabled, deprecated, and archived Skills are skipped during full installation.

## Updating An Existing Installed Skill

By default, install scripts refuse to overwrite an existing Skill.

Use `-Force` or `--force` to back up the current installed directory and copy the repository version:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-skill.ps1 -Skill fix-title -Force
powershell -ExecutionPolicy Bypass -File .\scripts\install-skill.ps1 -Skill repair-markdown-citations -Force
```

```bash
bash scripts/install-skill.sh fix-title --force
```

Backups are created next to the installed Skill:

```text
C:\Users\wangq\.agents\skills\fix-title.backup-YYYYMMDDHHMMSS
```

## Claude Link

To create or update the Claude private Skill entry as a link to the public installation surface:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-skill.ps1 -Skill fix-title -InstallClaudeLink
```

```bash
bash scripts/install-skill.sh fix-title --install-claude-link
```

Codex is not currently treated as a separate private install target for these shared automation Skills.