hooks-workflow
Generates hook configuration from language rules. Use when configuring Claude hooks, translating rule hook guidance, or verifying existing hook config.
SKILL.mdycc/skills/hooks-workflow/SKILL.md
GitHubhooks-workflow
This skill turns existing rule-file hook guidance into real, target-appropriate
hook configuration. It reads ycc/rules/<language>/hooks.md (plus
ycc/rules/common/hooks.md when present), resolves which hook events the
requested target actually supports by consulting the capability matrix, and
invokes build-hook-config.sh to emit the correct artifact. Explicit
per-target boundaries are enforced at every step: Claude receives a concrete
JSON hooks settings fragment, Cursor receives a rule-embedded .mdc advisory
where the matrix shows partial support, and Codex always receives an
advisory-only config.toml fragment. The skill never claims parity across
targets and never fabricates config for a target the matrix marks as
unsupported.
When to use
- You want a real
hooksblock in~/.claude/settings.jsongenerated from the project's existing rule guidance. - You want to know which hook events are supported on Cursor or Codex before spending time writing config.
- You want to verify that previously emitted hook config is still parseable and that any referenced command binaries are present.
- You want a dry-run preview of what the skill would emit without writing any files.
- You want an advisory-only Codex fragment that documents hook intent even though Codex hooks are not yet in GA.
Arguments
Parse $ARGUMENTS for:
- language (required, first positional) — the rules subdirectory name, e.g.
python,typescript,go. The skill resolves this toycc/rules/<language>/hooks.md. UseGlobonycc/rules/*/to list valid values; abort with the full list if the provided value does not match. - --target (default
claude) — one ofclaude,cursor, orcodex. Determines which output format is produced and which matrix cells are checked. - --event (default
all) — one ofPreToolUse,PostToolUse,Stop, orall. Restricts which hook events are included in the emitted config. Passingallincludes every event the matrix marks as supported or partial for the resolved target. - --out (default varies by target) — explicit output path. Defaults:
Claude →
~/.claude/settings-hooks-fragment.json; Cursor →ycc/rules/<language>/hooks-cursor.mdc; Codex →ycc/rules/<language>/hooks-codex.toml. - --dry-run — print the full plan and the would-be output, write nothing, and stop before invoking any scripts.
- --verify — after writing the output file, invoke
verify-hooks.shto run parse-only checks and probe referenced command binaries. - --force — required when writing Codex output to disk. Without this flag, Codex output is printed to stdout only. Has no effect on Claude or Cursor targets.
Phases
Phase 0: Reload the capability matrix
Read ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/target-capability-matrix.md
in full. Hold the parsed table in context for all subsequent matrix lookups.
Do not use stale or cached matrix data from a previous run.
Phase 1: Resolve language and source rules files
Use Glob to list all directories matching ycc/rules/*/. Extract the
directory name (the trailing path segment) from each match to build the valid
language list.
If the provided <language> is not in that list, STOP and emit:
Unknown language "<language>". Valid values: <sorted list of discovered names>.
Resolved sources (read both if they exist; skip silently if absent):
ycc/rules/<language>/hooks.md— language-specific hook recommendationsycc/rules/common/hooks.md— cross-language hook recommendations
If neither file exists, STOP and emit:
No hooks.md found under ycc/rules/<language>/ or ycc/rules/common/.
Nothing to generate.
Phase 2: Resolve target and check matrix support
For each event in the resolved --event set, look up the HOOKS.<event> row
and the --target column in the matrix loaded in Phase 0.
Cell verdicts:
supported— proceed normally.partial— proceed but prefix the output block with the relevant Notes entry from the matrix, verbatim.unsupported— STOP for that event and emit:
HOOKS.<event> is not supported on target <target>.
Matrix row: | HOOKS.<event> | <claude cell> | <cursor cell> | <codex cell> |
<If a different target supports it, note: "HOOKS.<event> is supported on <other target>.">
If --event all was passed and every event is unsupported for the chosen
target, STOP entirely after emitting the unsupported messages for all events.
Phase 3: Parse hook recommendations
Read the resolved source file(s) from Phase 1. Extract each hook
recommendation: the triggering event, the matcher pattern or tool name (if
any), and the command to run. Use Grep if needed to locate the structured
sections within the file.
If a source file exists but contains no parseable hook recommendations, note this in the output and continue (there may still be advisory content worth emitting).
Phase 4: Invoke build-hook-config.sh
The builder requires canonical ycc/rules/*/hooks.md sources, the compatibility
matrix, and hook templates. It discovers a source checkout or accepts
--repo-root=/path/to/checkout; installed bundles do not contain these sources.
Run:
${CLAUDE_PLUGIN_ROOT}/skills/hooks-workflow/scripts/build-hook-config.sh \
--language=<language> \
--target=<target> \
--event=<event> \
--out=<path> \
[--force]
Output format by target:
Claude — a JSON fragment containing only the
hookskey, suitable for merging into~/.claude/settings.json. Example structure:{ "hooks": { "PreToolUse": [...], "PostToolUse": [...], "Stop": [...] } }Cursor — a
.mdcrule-embedded fragment where the matrix showspartialsupport. Where an event isunsupported, the script emits an advisory-only marker comment instead of executable config.Codex — always an advisory-only
config.tomlfragment. The script MUST prefix the entire output with:# Advisory only — Codex hooks are under development; verify support in the installed CLI.Codex output is printed to stdout unless
--forcewas passed. If--forceis absent and--outresolves to a file path, STOP before writing and emit:Codex output requires --force to write to disk. Re-run with --force to confirm. Output printed to stdout: <content>
If build-hook-config.sh exits non-zero, surface the full stderr output and
STOP.
Phase 5: Verify (conditional)
If --verify was passed, run:
${CLAUDE_PLUGIN_ROOT}/skills/hooks-workflow/scripts/verify-hooks.sh \
--file <resolved-out-path> \
--target <target>
This script performs parse-only checks on the emitted file and probes each
hook command binary with --help or --version. It never executes a hook
body. Surface the full stdout and stderr from the script. If it exits non-zero,
report the failure without rolling back the written file.
Phase 6: Emit produced paths and matrix justification
After all phases complete, always emit:
The absolute path(s) of the file(s) written (or "no file written" if
--dry-runor Codex without--force).The matrix row(s) that justified the decision, quoted verbatim from the matrix table. For example:
Matrix justification: | HOOKS.PreToolUse | supported | partial | unsupported |
Anti-parity stance
This skill refuses to fabricate config for an unsupported target. If the matrix
cell is unsupported, the skill stops for that event and reports exactly what
the matrix says. There is no fallback, no silent downgrade, and no invented
config.
Dry-run mode (--dry-run) always emits the advisory text — including any
unsupported notices derived from the matrix — and stops before writing any
file. A dry run that encounters an unsupported cell is informational, not an
error; it shows what would have been blocked.
Notes
- For per-target capability explanations and known limitations, see
${CLAUDE_PLUGIN_ROOT}/skills/hooks-workflow/references/support-notes.md. - Run
scripts/build-hook-config.shwhen rendering hook config (Step 2); the script reads the three per-target templates internally. Read a template only when inspecting its output:references/templates/claude-settings.json.tmpl(Claude target),references/templates/codex-config-fragment.toml.tmpl(Codex target), andreferences/templates/cursor-rule-fragment.mdc.tmpl(Cursor target). - The authoritative capability verdicts live in
${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/target-capability-matrix.md. Do not override matrix verdicts locally.