# Skill Usage Reminder Index

Status: Active advisory hook catalog

## Purpose

This index lists the high-impact skill workflows that
`hooks/codex/skill-usage-reminder.py` watches for on `UserPromptSubmit`.
The reminder only tells the active agent to consider a
`skill-usage.record.v1` envelope. It does not create evidence directories,
write records, infer outcomes, or replace the calling skill contract.

## Source Of Truth

- Machine-readable catalog:
  `hooks/codex/skill-usage-reminder.skills.json`
- Hook implementation:
  `hooks/codex/skill-usage-reminder.py`
- Quick lookup:
  `uv run --locked python hooks/codex/skill-usage-reminder.py --list`
- JSON lookup:
  `uv run --locked python hooks/codex/skill-usage-reminder.py --list --format json`

Keep this document aligned with the catalog when adding or removing watched
skills. The catalog is the parseable source of truth; this file is the human
lookup surface.

## Tiers

- `default`: broad enough to match common action phrases plus exact skill links.
- `exact-only`: only exact skill-name aliases are configured, so generic phrases
  such as "create skill" do not trigger the hook by themselves.

## Reminder Catalog

| Skill | Tier | Why it is watched |
| --- | --- | --- |
| `browser-qa` | default | Browser-facing QA usually creates validation and browser evidence artifacts. |
| `code-review-specialists` | default | Specialist review workflows create retained review findings for broad or risky diffs. |
| `create-github-pr` | default | GitHub PR creation is provider-side delivery state. |
| `deliver-github-pr` | default | GitHub PR delivery spans validation, checks, provider state, and merge handling. |
| `close-github-pr` | default | GitHub PR close/merge changes provider-side delivery state. |
| `create-gitlab-mr` | default | GitLab MR creation is provider-side delivery state. |
| `deliver-gitlab-mr` | default | GitLab MR delivery spans validation, pipelines, provider state, and merge handling. |
| `close-gitlab-mr` | default | GitLab MR close/merge changes provider-side delivery state. |
| `create-dispatch-lane-pr` | default | Dispatch lane PR creation links plan execution state to provider delivery state. |
| `gh-fix-ci` | default | Automated CI repair can modify code, push commits, and iterate on remote checks. |
| `release-workflow` | default | Release workflows change public version, tag, changelog, and distribution state. |
| `find-and-fix-bugs` | default | Autonomous bug-fixing can scan, edit, validate, commit, and open PRs. |
| `fix-bug-pr` | default | Bug PR repair changes existing provider-visible remediation state. |
| `semgrep-find-and-fix` | default | Security automation can scan, triage, edit, and open report or fix PRs. |
| `issue-follow-up` | default | Issue follow-up turns discovered work or blockers into durable provider state. |
| `issue-lifecycle` | default | Issue lifecycle owns durable planning state in GitHub Issues. |
| `dispatch-pr-review` | default | Dispatch PR review ties provider comments, findings, issue state, and merge decisions together. |
| `dispatch-issue-closeout` | default | Dispatch issue closeout reviews subagent lanes, merges PRs, and closes plan-issue runtime work. |
| `dispatch-subagent-pr` | default | Dispatch subagent PR work owns an implementation lane and provider PR handoff. |
| `dispatch-plan-delivery` | default | Dispatch plan delivery coordinates sprint execution, subagent PRs, and acceptance gates. |
| `create-plan` | default | Plan creation writes durable implementation artifacts that guide later execution. |
| `create-dispatch-plan` | default | Dispatch plans add sprint, PR lane, and subagent execution metadata. |
| `execute-from-plan` | default | Plan execution performs implementation work against a durable execution-state ledger. |
| `execute-plan-parallel` | default | Parallel plan execution dispatches subagents, integrates changes, and validates results. |
| `docs-plan-cleanup` | default | Plan cleanup removes or reconciles durable coordination artifacts. |
| `durable-artifact-cleanup` | default | Durable artifact cleanup removes obsolete implementation artifacts after execution. |
| `create-skill` | exact-only | Skill lifecycle changes affect future agent behavior and should be traceable when invoked. |
| `create-project-skill` | exact-only | Project-local skill lifecycle changes affect future project agent behavior. |
| `remove-skill` | exact-only | Skill removal is a breaking lifecycle change and should have retained context. |

## Compatibility And Exclusions

- `browser-qa` is the canonical watched workflow. `web-qa` remains a configured
  alias for compatibility, not a separate reminder skill.
- Evidence primitives such as `skill-usage`, `review-evidence`,
  `test-first-evidence`, `web-evidence`, `browser-session`, and `canary-check`
  are intentionally excluded because parent workflows should link those child
  records.
- `semantic-commit` and `semantic-commit-autostage` are intentionally excluded
  because commit workflows are routine repository mechanics and are often called
  inside a parent workflow that already owns the retained context.
- Routine reporting or lookup skills should not be added just because they can
  call external sources. Add them only if the workflow creates durable records or
  repeatedly exposes a skill-contract gap.
