setup
Verify bash-format's prerequisites and configuration here, and register its git pre-commit entry. Use when: 'set up bash-format', 'configure bash-format', 'is bash-format working', shell lint or formatting silently isn't happening, or a hook reported a missing prerequisite or drifted git hook. Actions: check (read-only verification, default) | apply | apply install-git-hooks [scope=local|shared]. Re-runnable.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 30
- Forks
- 7
01 前言 Front Matter
- shell
- bash
- description
- Verify bash-format's prerequisites and configuration here, and register its git pre-commit entry. Use when: 'set up bash-format', 'configure bash-format', 'is bash-format working', shell lint or formatting silently isn't happening, or a hook reported a missing prerequisite or drifted git hook. Actions: check (read-only verification, default) | apply | apply install-git-hooks [scope=local|shared]. Re-runnable.
- allowed-tools
- [ "Bash(command -v jq*)", "Bash(command -v node*)", "Bash(command -v shellcheck*)", "Bash(command -v shfmt*)", "Bash(node \"${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/install.mjs\" verify:*)", "Bash(node ${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/install.mjs verify:*)", "Bash(node \"${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/install.mjs\" plan:*)", "Bash(node ${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/install.mjs plan:*)" ]
- argument-hint
- [check|apply [install-git-hooks [scope=local|shared]]]
- user-invocable
- true
- disable-model-invocation
- true
02 资源文件 1
- 参考文档reference/git-hook-decisions.md5.0 KB
03 SKILL.md 正文
Pre-computed context
check's tool probes ran at load time. Read these rows instead of re-issuing them; each shows the
tool's path when present, or absent when missing:
jq: !command -v jq 2>/dev/null || echo absentnode: !command -v node 2>/dev/null || echo absentshellcheck: !command -v shellcheck 2>/dev/null || echo absentshfmt: !command -v shfmt 2>/dev/null || echo absent
A row reading [shell command execution disabled by policy] carries no result: run that tool's
command -v probe via Bash instead.
- Pointer: for the placeholder a skipped load-time command leaves, fetch skills § Inject dynamic context live.
- As of: 2026-11-11
- Recheck trigger: the placeholder text changes.
Purpose
Thin check-centric setup per the uniform setup contract (docs/plugin-philosophy.md
"Setup is explicit and repeatable" in the marketplace repository): check inspects and
reports, apply resolves. The only consumer-project files this plugin owns are its git-hook
entry copies, which apply install-git-hooks writes. Linting rules come from the repository's
own .shellcheckrc, formatting from its .editorconfig, and the tunables are the native
userConfig options (the on/off toggle, the gitignored-file switch and the end-of-turn check).
Every prerequisite is a PATH binary the plugin never bundles, and the plugin never installs
system packages, so the rest of apply is guidance-only. It never modifies user settings or the
plugin cache.
Action routing: no argument or check runs the check; apply runs the check first, then
offers remediation guidance. Both are non-interactive. Never prompt when the action is given.
apply install-git-hooks asks only where its section says to.
check (read-only)
The batch hook (${CLAUDE_PLUGIN_ROOT}/hooks/bash-format.sh), the pre-commit check
(${CLAUDE_PLUGIN_ROOT}/git-hooks/shell-check.sh) and the shared rewrite helper
(${CLAUDE_PLUGIN_ROOT}/git-hooks/shfmt-rewrite.sh) are the single source of truth for what
they require and how they resolve things.
Read it first. Probe what it actually does, don't recite this file. Then read the
pre-computed tool rows, run the remaining probes via Bash, and report a PASS/FAIL/INFO
table with one remediation line per FAIL. Do not modify anything.
Read each option value from this text; never put a ${user_config.*} string in a shell command.
Open plugin files by the ${CLAUDE_PLUGIN_ROOT} paths this skill names; never Glob or Grep the plugin directory.
The format pass (the batch row and the pre-commit rewrite) and the lint pass (the pre-commit ShellCheck findings) are independent; report each separately.
When the plugin's toggle is disabled, every prerequisite absence except node downgrades from
FAIL to INFO. The hook exits through its enabled-gate before probing anything, so a deliberately
disabled plugin is not broken. Report the probes informationally and note that re-enabling
restores the FAIL semantics. A missing node stays FAIL in either state: every hook row launches
node, and the gate runs inside hooks/exec-bash.mjs. A tool the git pre-commit entry needs keeps
the grade it gets with the toggle on while that entry is installed (step 12 reports it as a tool
line beside an ok, stale or modified entry): the entry runs at commit outside Claude Code
and reads no toggle.
- Bash version. Check against the hooks' floor, Bash 3.2 or newer (
${CLAUDE_PLUGIN_ROOT}/hooks/hook-utils.sh). node. The pre-computednoderow. FAIL if absent: every hook row launches throughnode hooks/exec-bash.mjs, so withoutnodethe hook does not launch and no shell edit is formatted in the session (${CLAUDE_PLUGIN_ROOT}/README.mdRequirements).jq. The pre-computedjqrow. FAIL if absent: the batch row does nothing, since it reads the file paths withjq, and the pre-commit rewrite is skipped.shellcheck(lint pass). The pre-computedshellcheckrow. FAIL if absent: the pre-commit entry reports no findings.shfmt(format pass). The pre-computedshfmtrow. Its FAIL/INFO status depends on the.editorconfigopt-in below, because the format pass runs only when the repo has opted in:- opted in AND
shfmtabsent → FAIL: neither the batch row nor the pre-commit entry formats. - not opted in → INFO regardless of
shfmt: the format pass stays quiet by design (the repo chose not to format), so a missingshfmtis not a defect here.
- opted in AND
.editorconfigshell opt-in. Mirror the hook's opt-in logic (shfmt_governed/section_applies_to_shellin${CLAUDE_PLUGIN_ROOT}/git-hooks/shfmt-rewrite.sh), not merely "does an.editorconfigexist". The opt-in is an EditorConfig section that names shell files: a shell glob such as[*.sh],[*.bash], or[*.{sh,bash}](including path-prefixed forms like[**/*.sh]), discovered by walking up from the file's directory to the repo root and stopping at aroot = trueconfig. A bare[*]catch-all does NOT count (most repos only set line-ending / charset properties there). Path-only sections like[scripts/**]do NOT count either. Report as INFO: whether a governing shell section exists and therefore whether the format pass is active. If none exists, INFO-note the consequence per the hook's logic: shell files are left unformatted rather than rewritten to shfmt's built-in defaults..shellcheckrc. INFO: ShellCheck auto-discovers.shellcheckrcby walking up from the file's directory. Report whether one exists; its absence is not a FAIL (ShellCheck applies its own defaults).- Hook options. Report the effective values.
${user_config.bash_format_enabled}(unexpanded or empty means the manifest defaulttrue; any value other thantruedisables the hook).${user_config.bash_format_lint_gitignored}(unexpanded or empty means the manifest defaultfalse): unless it istrue, the batch row silently skips an edit to a file the repository gitignores, so a user asking why.work/scratch.shwas not formatted gets this answer.${user_config.bash_format_end_of_turn}(unexpanded or empty means the shipped defaultfalse), as INFO: on, the Stop row checks the uncommitted changes once per turn; off, only the batch format and the git pre-commit entry run. - Hook registration. INFO: confirm the plugin is enabled for this project
(
/plugin→ Installed) rather than parsing settings files. - Project scope. INFO: when
CLAUDE_PROJECT_DIRis set, the batch row acts only on shell files inside it (symlink-resolved membership guard in the shared hook library, aware of Windows 8.3 short-name spellings of in-project paths, a per-volume property; only volumes with 8.3 generation enabled produce them); a.sh/.bashfile written outside the project (temp/scratchpad dirs) is silently skipped. No lint, no format, no notice. The OS temp tree counts as outside even when it sits underCLAUDE_PROJECT_DIR, unless the project root itself lives under temp. WhenCLAUDE_PROJECT_DIRis unset (e.g. some headless-psessions) the guard is skipped and any existing edited file is processed. Report this so a greencheckis not read as "every shell edit anywhere is covered". - Gitignored files. INFO: unless
bash_format_lint_gitignoredistrue, a file the repository gitignores (git check-ignore) is silently skipped: no lint, no format, no notice. A tracked file that matches an ignore pattern stays in scope, and when git cannot decide (git absent, no repository, an error) the hook acts as before (hook::gitignored_out_of_scopein${CLAUDE_PLUGIN_ROOT}/hooks/hook-utils.sh). Report the item 8 value beside this. - Git pre-commit entry. Run
node "${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/install.mjs" verifyfrom the repository. Each line is<state>\t<entry>[\t<detail>]:okis PASS,declinedis INFO (this clone said no; silent at session start), andmissing,stale,modifiedorsupersededis a FAIL whose remediation isapply install-git-hooks; asupersededdetail lists what an install under an earlier plugin name left, which that action removes on the user's yes. Atool\t<tool>\tmissingline means the installed entry cannot run here: list every such tool with its install method from the${CLAUDE_PLUGIN_ROOT}/prerequisites.json(Read that path), so a lane or cloud setup script can provision it before an auto-mode session commits. Outside a git repository, report INFO and skip the step.
When every probe passes, report the result with the scope caveats (items 10 and 11). Never an unqualified "fully operational", which would imply out-of-project shell edits are covered when they are deliberately skipped.
apply install-git-hooks [scope=local|shared]
Registers the plugin's git-hook entries (git-hooks/entries.json) with the repository's hook
manager. The installer script only detects, renders and writes files the plugin owns; every step
that needs judgment comes back to you as a decisions[] item, which you reason about and apply
with your own edit tools.
- Scope. Use the argument when given. Otherwise, when the user is present, ask:
local(this clone only, nothing committed) orshared(committed under.githooks/bash-format/, so every teammate and agent gets it). When nobody can answer, uselocal. - Plan. Run
node "${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/install.mjs" plan --scope <scope>and read the JSON:manager,actions[],decisions[]. - Manager conflict. A
manager-conflictdecision lists the evidence (two managers, or one this installer does not drive, such as the pre-commit framework). Show it and ask which manager should carry the entry; rerunplanwith--manager lefthook|husky|plain. Without an answer, stop here and report. - Actions. When
actions[]holdscopyitems, runnode "${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/install.mjs" copy --scope <scope>(plus the same--managerwhen you passed one). It printsinstalled,refreshed,unchanged,refused,blocked,unsafe-pathorstage-failedper entry;refusedmeans a locally edited copy or dispatcher, which themodifieddecision covers,blockedthat another tool owns the local hooks directory, which thehooks-path-owneddecision covers,unsafe-paththe decision of that name, andstage-failedthatgit addfailed on a shared install: report it, since the team would not receive the files. - Decisions. Read reference/git-hook-decisions.md for
what each kind asks of you, apply each one, then rerun
planuntil only the decisions you chose to leave remain. - Verify. Run
verifyand report its lines ascheckstep 12 does.
The entry rewrites: at commit it formats the staged shell scripts an .editorconfig section
governs and stages the result, so tell the user that a commit can change the files it contains,
and that a partly staged governed script is refused untouched.
When the user does not want an entry in this clone, run
node "${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/install.mjs" decline --entry shell-check; the
session-start drift line then stays silent until verify runs by hand, and --undo reverses it.
Add --global (with or without --undo) to decline the entry in every clone;
git config --global checks.git-hooks.declined true declines every entry of every plugin, and an
entry's own key set to false in a clone opts that entry back in. The adoption
path explains to the user each scope and why a formatter's cleanup PR comes first.
apply (idempotent)
Run check, then for each FAIL point at the resolution. Apart from the git-hook entry above, this
skill installs nothing:
-
missing
shellcheck: install guidance from the README Requirements section (the ShellCheck install guide); this skill never installs system packages. -
missing
shfmtwhile the repo opts in: install guidance (shfmt); this skill never installs system packages. -
missing
node/jq/ Bash: platform install instructions from the README Requirements section. -
no shell
.editorconfigopt-in (and formatting is wanted): explain that adding a governing shell section ([*.sh],[*.bash], or[*.{sh,bash}]) to an.editorconfigopts the repo in. A bare[*]is not enough, but this skill does not write it..editorconfigis cross-cutting (it governs every editor and tool in the repo), so the choice and the edit belong to the consumer. -
toggle off, gitignored files wanted, or the end-of-turn check wanted: set
bash_format_enabled,bash_format_lint_gitignoredorbash_format_end_of_turntotruethrough Claude Code's native flow, interactively with/plugin configure bash-format@<marketplace>or by a headless route, as the marketplace's plugin-reconfiguration convention gives them in § The routes (it owns the verified-version record). Apply the scope and failure-signal caveats in its § Caveats every setup skill's short form carries. Read both sections and print what they give, the fallback route, its behavior on an already-installed plugin and the scope to pass included, rather than only naming them, and leave out the verified-version record. Never uninstall to reconfigure; that section links what an uninstall deletes. This skill never writes user settings orpluginConfigs. Afterwards reruncheckin a fresh session, since a same-sessioncheckcan still show the old value, and report the observed effective value, never an unobserved change.- Pointer: for the headless command's flags, how it reports a saved or refused value, and when a saved value applies, fetch plugin CLI reference § plugin configure live.
After pointing at a remediation, re-run the relevant check probe live via Bash (a pre-computed row
predates the remediation, so never re-read it) and report its actual result. Never claim resolved on
the reader's report that they installed something.
Re-running apply after everything passes changes nothing and reports "already configured".
What this skill does NOT do
- Run the linter or formatter. Editing any
.shor.bashfile exercises the batch row end to end;git commitexercises the installed pre-commit entry. - Write the plugin cache, Claude Code user settings, or
pluginConfigs. Nor the repository, beyond the git-hook entry copies, including.editorconfig/.shellcheckrc. Every prerequisite is aPATHbinary or the native toggle, so remediation is guidance only. - Download or execute tools during
checkbeyond the read-onlycommand -vpresence probes.
Gotchas
ENAMETOOLONGwhen grepping the plugin cache. Installed plugins run from a deeply nested, cache-isolated path. Piping agrep/rgover the long absolute path tohooks/hook-utils.sh(or another bundled file) can spawn-fail withENAMETOOLONGon some hosts. Read the file directly rather than passing the full cache path on the command line.checkPASS ≠ every shell edit is covered. WhenCLAUDE_PROJECT_DIRis set the hook is project-scoped (probe 10): shell files written outside it are silently skipped, so a fully greencheckstill does not cover out-of-project edits. (WhenCLAUDE_PROJECT_DIRis unset the scoping does not apply. See probe 10.)shfmtFAIL is opt-in-conditional. A missingshfmtis only a FAIL when an.editorconfigsection governs shell files; without that opt-in it is INFO, not a defect. Resolve the.editorconfigopt-in state before callingshfmta failure.
04 同仓库更多 Skills
track
Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.
reviewer-media
Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
principles
Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.
write
Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').