# Importing and using HRFocus Codex skills

## What a skill package contains

Each ZIP contains one top-level skill folder. The folder must contain `SKILL.md`; it may also contain `agents`, `references`, `scripts`, and `assets`.

Do not extract a skill so that it gains an extra nested folder. The correct result is:

```text
C:\Users\YourName\.codex\skills\skill-name\SKILL.md
```

## Install one skill in Codex Desktop

1. Download the required ZIP from `01 Skills\Packages` or the Development Resources website.
2. Close any task that is actively using an older copy of the same skill.
3. Determine the local skills folder:
   - If `CODEX_HOME` is defined, use `%CODEX_HOME%\skills`.
   - Otherwise use `%USERPROFILE%\.codex\skills`.
4. If a folder with the same skill name already exists, compare or back it up before replacing it. Do not blindly merge different versions.
5. Extract the ZIP directly into the local skills folder.
6. Confirm that `<skills folder>\<skill name>\SKILL.md` exists.
7. Start a new Codex task. The skill becomes available on the next task/turn after installation.

PowerShell example:

```powershell
$skillsRoot = if ($env:CODEX_HOME) {
    Join-Path $env:CODEX_HOME 'skills'
}
else {
    Join-Path $env:USERPROFILE '.codex\skills'
}

New-Item -ItemType Directory -Path $skillsRoot -Force | Out-Null
Expand-Archive -LiteralPath 'C:\Downloads\build-hrfocus-dtu-integration.zip' -DestinationPath $skillsRoot
Test-Path -LiteralPath (Join-Path $skillsRoot 'build-hrfocus-dtu-integration\SKILL.md')
```

## Install the complete bundle

Download `HRFocus-Reusable-Skills-All.zip` and extract it into the same skills folder. The archive contains one top-level folder per skill.

Before installing the bundle, review the catalog and avoid overwriting newer local changes. The bundle is most suitable for a new workstation or a controlled team refresh.

## Use a skill

Invoke a skill explicitly by placing `$` before its name:

```text
Use $dynamic-form-builder to build a complete employee declaration form from this approved specification.
```

Codex may also select a skill automatically when the request matches its description. Explicit invocation is preferable when a particular workflow or validator is required.

Each skill's example prompts are listed in `01 Skills\001 - Skills Catalog.md` and on the website.

## Update or remove a skill

- Update: compare the existing folder, preserve approved local changes, then replace it with the reviewed package.
- Remove: close active tasks, move the skill folder to an archive location, and start a new task.
- Never install `.system` skills from this share; Codex manages its built-in system skills.

## Validation and security

- Compare the downloaded ZIP SHA-256 value with `01 Skills\002 - Package Checksums.csv`.
- Inspect `SKILL.md`, scripts, assets, and references before first use.
- Do not add passwords, API keys, bearer tokens, private keys, production personal data, or client connection strings to a shared skill.
- Treat scripts as source code: review them before execution and run with the minimum required permissions.
- Keep client-specific deliverables under Support Solutions; keep only reusable patterns inside the skill library.

## Optional API-managed skills

OpenAI's Skills API accepts a skill directory upload or a single ZIP file. This is separate from the local Codex Desktop folder installation described above. Use only an approved organisational API project and follow the platform's access controls: https://developers.openai.com/api/reference/python/resources/skills/methods/create

## Troubleshooting

- Skill not listed: confirm `SKILL.md` is directly below the named skill folder and start a new task.
- Duplicate skill: remove or archive the older same-named folder; do not retain two active copies.
- Script blocked: review execution policy, file provenance, permissions, and the script itself before unblocking it.
- Wrong behavior: invoke the skill explicitly, verify the installed version/checksum, and inspect its referenced standards.