154 lines
4.9 KiB
Markdown
154 lines
4.9 KiB
Markdown
# 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.
|
|
|
|
The shared environment includes `pyyaml` so Skill metadata validation can also run inside the repository environment. Do not fall back to bare `python` for validation just because the base Miniconda environment happens to have extra packages.
|
|
|
|
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 -B -m unittest discover -s skills\fix-title\tests -v
|
|
conda run -n skills-vault python -B .\skills\fix-title\scripts\fix_markdown_titles.py --help
|
|
conda run -n skills-vault python -B C:\Users\wangq\.codex\skills\.system\skill-creator\scripts\quick_validate.py skills\bundle-zip
|
|
```
|
|
|
|
Do not rely on bare `python` unless you have first verified it resolves to `C:\Users\wangq\.conda\envs\skills-vault\python.exe`.
|
|
|
|
Use repository-local temp paths for tests by default. Point `TMP` and `TEMP` at an ignored directory under `tmp\` before running pytest, instead of relying on the Windows user temp directory:
|
|
|
|
```powershell
|
|
New-Item -ItemType Directory -Force -Path tmp\pytest | Out-Null
|
|
$env:TMP = (Resolve-Path -LiteralPath tmp\pytest).Path
|
|
$env:TEMP = $env:TMP
|
|
conda run -n skills-vault pytest skills\voice-generation\tests -q
|
|
```
|
|
|
|
Repository Markdown, docs, fixtures, and other text files are UTF-8 by default. In PowerShell, prefer explicit UTF-8 reads/writes, for example:
|
|
|
|
```powershell
|
|
Get-Content -LiteralPath README.md -Encoding UTF8
|
|
Set-Content -LiteralPath output.md -Value $text -Encoding UTF8
|
|
```
|
|
|
|
## Install One Skill
|
|
|
|
PowerShell:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\scripts\install-skill.ps1 -Skill bundle-zip
|
|
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 bundle-zip
|
|
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 bundle-zip -Force
|
|
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 bundle-zip --force
|
|
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.
|