agent-skills

Versioned home for reusable Codex skills.

Why this repo exists

~/.codex/skills is runtime state, not a durable source of truth. This repository keeps skill definitions under Git so changes are reviewable, reproducible, and easy to sync across machines.

Layout

• skills/: skill folders (each contains SKILL.md and optional assets/scripts)
• scripts/install-skills.sh: sync skills from this repo to a Codex runtime

Current managed skills

• adr-review-assistant
• claude-cli
• init-docs-workflow
• install-subagent-replay-loop

Interdependencies

• init-docs-workflow with ADR mode (--with-adr, especially --with-cron) is designed to pair with adr-review-assistant.
• Rationale:
  • ADR cron generates candidate queues only.
  • Human/operator review is still required for promotion/disposition.
  • qualifying strict candidates may be accepted directly from the queue, while the rest continue through proposed.
  • adr-review-assistant provides the operator-in-the-loop review flow for candidate triage and optional proposed ADR decisions.
  • candidate review writes both human-readable *-review.md logs and sibling *-review.jsonl metadata so future candidate generators can reuse concrete defer reasons as suppression hints.

Quick start

cd /path/to/agent-skills
bash scripts/install-skills.sh --all

This installs skills into ${CODEX_HOME:-$HOME/.codex}/skills.

Install options

# Install one skill
bash scripts/install-skills.sh --skill init-docs-workflow
bash scripts/install-skills.sh --skill adr-review-assistant
bash scripts/install-skills.sh --skill claude-cli

# Install docs-workflow companion bundle (recommended for ADR workflows)
bash scripts/install-skills.sh --bundle docs-workflow

# Install all skills (default)
bash scripts/install-skills.sh --all

# Dry-run
bash scripts/install-skills.sh --all --dry-run

# Use symlinks instead of file copies
bash scripts/install-skills.sh --all --mode symlink

# Override target path
bash scripts/install-skills.sh --all --target /custom/path/.codex/skills

Operational notes

• Default mode is copy with backup of existing target skills.
• Backups are written under <target>/.backup/<timestamp>/.
• For deterministic environments (CI/servers), prefer --mode copy.

Import from runtime (optional)

If you edited a skill directly under ~/.codex/skills, import it back into this repo:

bash scripts/import-skill.sh --skill init-docs-workflow

Install Subagent Replay Loop skill usage

Install replay-loop tooling into a repository:

bash "${CODEX_HOME:-$HOME/.codex}/skills/install-subagent-replay-loop/scripts/install-subagent-replay-loop.sh" \
  --repo /path/to/repo \
  --dry-run

bash "${CODEX_HOME:-$HOME/.codex}/skills/install-subagent-replay-loop/scripts/install-subagent-replay-loop.sh" \
  --repo /path/to/repo

Or install it as part of docs workflow bootstrap:

bash "${CODEX_HOME:-$HOME/.codex}/skills/init-docs-workflow/scripts/init-docs-workflow.sh" \
  --repo /path/to/repo \
  --profile core \
  --with-replay-loop

Use init-docs-workflow --with-replay-loop when you also want docs policy/guide integration, not just script installation.