---
name: codex-project-skill-auto-install
description: Load when a teammate opens zhctprompt in Codex on a local Mac, project skills may not be installed in ~/.codex/skills, or the user asks Codex to automatically install project skills through a child/background thread.
version: 0.1.0
---

# Codex Project Skill Auto Install

## Purpose

Make a freshly cloned `zhctprompt` usable in Codex without asking the teammate to manually copy 90+ project skills.

The project skill source of truth remains:

```text
standards-stack/agent-skills/skills/
```

The local Codex skill registry target is:

```text
$HOME/.codex/skills/
```

## Trigger

Use this skill when:

- a teammate opens `zhctprompt` on a Mac in Codex after cloning or pulling the project;
- a task starts in `zhctprompt` and `$HOME/.codex/skills/codex-team-skill-handoff/SKILL.md` is missing;
- the user says skills should be installed automatically, in a child thread, background thread, or Codex internal skills;
- the user asks to prepare this project for another teammate's local Codex environment.

## Workflow

1. Run `zhctprompt-self-update-on-qa` first when project rules require it. If self-update stops because the worktree is dirty or pull is blocked, continue only if the user explicitly allows continuing from the current tree.
2. Check whether local project skills appear installed:

```bash
test -f "$HOME/.codex/skills/codex-team-skill-handoff/SKILL.md"
test -f "$HOME/.codex/skills/codex-project-skill-auto-install/SKILL.md"
```

3. If the Codex app exposes a background thread tool, start a child/background thread using `references/child-thread-prompt.md`. Do not wait for it unless the current task specifically depends on local skill installation.
4. If no child-thread tool is available, run the install script inline:

```bash
bash standards-stack/agent-skills/scripts/install_project_skills_to_codex.sh
```

5. If the teammate only wants a preview, or if you are validating this workflow without changing the current machine, use:

```bash
bash standards-stack/agent-skills/scripts/install_project_skills_to_codex.sh --dry-run
```

6. Report the result and the local report path:

```text
$HOME/.codex/zhctprompt-project-skill-install-report.md
```

## Boundaries

- Copy only `standards-stack/agent-skills/skills/` into `$HOME/.codex/skills/`.
- Do not copy personal memory files, connector state, browser profiles, OAuth cookies, cloud tokens, API keys, project secrets, or the whole `$HOME/.codex` directory.
- Do not use `--delete` against `$HOME/.codex/skills`; teammates may have personal skills outside this project.
- Do not claim child-thread installation occurred if the thread tool was unavailable or the script was only dry-run.
- Project-reference mode remains valid even if local install is blocked; `AGENTS.md` can still load skills from project paths.

## Validation

Run at least:

```bash
bash standards-stack/agent-skills/scripts/install_project_skills_to_codex.sh --dry-run
bash -n standards-stack/agent-skills/scripts/install_project_skills_to_codex.sh
find standards-stack/agent-skills/skills -mindepth 2 -maxdepth 2 -name SKILL.md -print | wc -l
```

After a real install, verify:

```bash
test -f "$HOME/.codex/skills/codex-team-skill-handoff/SKILL.md"
test -f "$HOME/.codex/skills/codex-project-skill-auto-install/SKILL.md"
```