formatters
Bootstraps project linting and formatting tools. Use when installing formatters, adding lint scripts, or wiring lint CI and pre-commit hooks.
SKILL.md.agents-plugin/skills/formatters/SKILL.md
GitHubFormatters Bootstrap
Installs a best-practices lint/format environment into a target project. Does not reimplement linter dispatch — it drives the repo's own scripts/style.sh init --copy|--sync machinery and adds documentation, aliases, CI, and hook wiring on top.
Operational context: Install the self-contained scripts/style.sh bundle and per-language configs, add package.json/Makefile/justfile aliases and project docs, and optionally wire CI and pre-commit hooks. Preserve managed-manifest idempotency; --sync is the rerun path.
Current Target Context
- Profile detection (complete
key=valueoutput,project_rootlast): !~/.agents/skills/formatters/scripts/profile-style.sh
Context injection is one scoped helper call: no pwd, head, 2>/dev/null, or pipeline. Compound pipelines are host-permission behavior (a headless caller allowlist may reject them even when each segment is allowed), and head -30 previously dropped profile keys. Do not widen allowed-tools with head, find, wc, or pwd; run each helper as a single command.
Arguments
| Flag | Meaning | Example |
|---|---|---|
--dry-run |
Preview every planned file; make no writes | formatters --dry-run |
--force |
Overwrite existing tool configs / aliases / docs without prompting | formatters --force |
--yes |
Non-interactive; keep existing files on conflict | formatters --yes |
--sync |
Install bundle + prune stale managed files (preferred on re-run) | formatters --sync |
--copy |
Install bundle without pruning (default when no manifest exists) | formatters --copy |
--ci |
Also emit .github/workflows/lint.yml and .github/workflows/lint-autofix.yml |
formatters --ci |
--no-autofix |
With --ci: skip lint-autofix.yml, install the check workflow only |
formatters --ci --no-autofix |
--hooks |
Also wire a pre-commit hook (lefthook preferred, husky if detected) | formatters --hooks |
--no-aliases |
Skip package.json / Makefile / justfile alias injection | formatters --no-aliases |
--no-docs |
Skip README section append | formatters --no-docs |
--target=<dir> |
Target directory (default: $PWD) |
formatters --target=~/projects/app |
--profile=<lang> |
Override detection: rust, ts-node, python, go, docs, mixed |
formatters --profile=rust |
--rust / --ts / --python / --go / --docs / --shell |
Enable specific stack(s); suppresses auto-detection | formatters --rust --go |
--all |
Install every supported stack's configs regardless of detection | formatters --all |
Flags are composable. See references/flag-reference.md for the full matrix and precedence rules. See references/best-practices.md for per-language tool rationale.
Questions: class confirm-destructive ("Proceed with install?"); headless (no question tool or chat turn): abort the install and print rerun with --yes. See ~/.agents/ycc-shared/references/question-policy.md.
Task
Execute the phases in order. Phases are short — do not add narrative prose between them.
Phase 0 — Parse flags
Extract booleans from $ARGUMENTS:
DRY_RUN,FORCE,YES,CI,NO_AUTOFIX,HOOKS,NO_ALIASES,NO_DOCSTARGET— value of--target=<dir>; default to$PWDPROFILE— value of--profile=<lang>; empty if unset- Per-stack booleans:
RUST,TS,PYTHON,GO,DOCS,SHELL;ALLfor--all SYNC_MODE— true if--syncpassed;COPY_MODE— true if--copypassed
Validation:
- Reject both
--syncand--copypassed together. - If
TARGETdoes not exist as a directory, abort.
Phase 1 — Profile
Run ~/.agents/skills/formatters/scripts/profile-style.sh "$TARGET" as one command. Keep every key (including project_root, docs_target, and hook/CI keys); parse the returned text in the caller. If an applier needs --profile-file, save that complete text with Write rather than an outer redirect or pipeline.
Stack-flag resolution:
- If
ALL=true→ enable all per-stack flags. - Else if
PROFILEis set → force per-stack flags from the profile mapping (seereferences/flag-reference.md--profiletable). - Else if any explicit per-stack flag was passed → use only the ones passed; do NOT override with auto-detection.
- Else → enable each stack whose
detect_*=truein the profile.
Mode resolution:
- If
SYNC_MODE→ use--sync. - Else if
COPY_MODE→ use--copy. - Else if
has_style_bundle=true→ use--sync. - Else → use
--copy.
Phase 2 — Plan preview
Print a plan block listing what will happen. Format:
Target: <TARGET>
Mode: --sync | --copy
Stacks: rust, ts, python, go, docs, shell
Bundle install: scripts/style.sh, scripts/format.sh, scripts/lint.sh, scripts/init-formatters.sh,
scripts/install-shellcheck.sh, scripts/go-tools.sh, scripts/lib/*,
scripts/templates/* (managed bundle files)
Tool configs: rustfmt.toml, clippy.toml, .golangci.yml, biome.json, tsconfig.json, package.json*,
pyproject.toml*, .markdownlint.json, .markdownlintignore, .prettierrc, .prettierignore
(* stack-aware scaffold / refuses to overwrite existing)
Aliases: (skipped if --no-aliases) package.json / Makefile / justfile
Docs: (skipped if --no-docs) README.md / CONTRIBUTING.md / AGENTS.md / AGENTS.md
CI workflows: (only if --ci) .github/workflows/lint.yml
.github/workflows/lint-autofix.yml (unless --no-autofix)
Pre-commit hook: (only if --hooks) lefthook.yml or .husky/pre-commit
Note each item that will be skipped (existing config, manifest detected, etc.).
Phase 3 — Dry-run / Confirm gate
- If
DRY_RUN=true→ run each sub-script with--dry-runto preview the writes, then STOP. - Else if
YES=falseandFORCE=false→ ask the user "Proceed with install? (yes / no)"; abort on anything other than an affirmative. - Else proceed.
Phase 4 — Install bundle + tool configs
Invoke the self-contained installer shipped inside the skill:
STYLE_SH="${HOME}/.agents/skills/formatters/scripts/bundle/style.sh"
Build init_args:
- Mode flag:
--syncor--copyper Phase 1. --target "$TARGET".- Per-stack flags: for each enabled stack, append
--rust|--ts|--python|--go|--docs|--shellas appropriate. - Overwrite policy:
--forceifFORCE=true,--yesifYES=true,--dry-runnever (dry-run is handled in Phase 3).
Run:
"$STYLE_SH" init "${init_args[@]}"
Surface its stdout. If it exits non-zero, STOP and surface the error verbatim.
Phase 5 — Aliases, docs, CI, hooks (parallel-safe, sequential-ok)
Unless suppressed, run each applier. Each writes to a distinct file so they can run sequentially with no conflicts. For each, prefer --force when FORCE=true.
Aliases (skipped if
NO_ALIASES=true):~/.agents/skills/formatters/scripts/apply-aliases.sh --target "$TARGET" [--force]Docs (skipped if
NO_DOCS=true):~/.agents/skills/formatters/scripts/apply-docs.sh --target "$TARGET" --profile-file "$PROFILE_FILE" [--force]CI (only when
CI=true):~/.agents/skills/formatters/scripts/apply-ci.sh --target "$TARGET" --profile-file "$PROFILE_FILE" [--force] [--no-autofix]Pass
--no-autofixwhenNO_AUTOFIX=trueto install only the check workflow. The check workflow runs on every PR and on pushes to the default branch andrelease/**. The autofix workflow runs on same-repo PRs to the default branch (origin/HEAD, falling back tomain), applies./scripts/style.sh format+lint --fix, and pushes fixes back asgithub-actions[bot]; fork PRs are skipped becauseGITHUB_TOKENcannot push to them.Hooks (run when
HOOKS=true, OR when the target already has alefthook.yml/.husky/pre-commit— i.e.,has_lefthook=trueorhas_husky=truein the profile):~/.agents/skills/formatters/scripts/apply-hooks.sh --target "$TARGET" --profile-file "$PROFILE_FILE" [--force]The auto-trigger keeps managed
style-lint/style-formatcommands in sync on every--syncre-run without forcing first-time hook installation on users who never asked for it.apply-hooks.shis idempotent: when managed commands are already present, it logs a no-op; otherwise it merges them in (lefthook) or skips if a non-empty.husky/pre-commitexists without--force(husky).
If any applier exits non-zero, report the failure and continue with the remaining ones — do not let a single applier abort the whole run.
Phase 6 — Summary report
Produce a summary with these sections:
- Bundle install — lines from
style.sh init(created, overwritten, skipped counts). - Tool configs — per-stack: written / skipped-existing / refused-to-overwrite (for
pyproject.toml). - Aliases — strategy chosen (package-json / makefile / justfile) and alias keys installed.
- Docs — which file was appended or created; section name.
- CI — paths written (
lint.ymlalways;lint-autofix.ymlunless--no-autofix), or "not requested". - Hooks — tool used (lefthook / husky / native), path written, or "not requested".
- Next steps — any of:
git config commit.template .gitmessage(unrelated to this skill but often useful alongside)lefthook install(if--hooks+ lefthook chosen)- Review
scripts/bundle in the first commit that adds it - Re-run with
formatters --syncafter upstream bundle changes - Bypass a single hook run:
git commit --no-verify
Important Notes
- Source of truth is
scripts/style.sh. This skill is an orchestrator; it never reimplements linter dispatch. Upgrading the upstream bundle propagates to installed targets viaformatters --sync. - Never overwrites user-authored configs silently.
apply-aliases.shpreserves existingpackage.jsonscripts unless--force.style.sh init-formatters.shrefuses to overwrite an existingpyproject.toml. Tool configs (prettier, biome, markdownlint, clippy, rustfmt) are skipped when present unless--force. - Detection is ignore-aware. Auto-detection enumerates only project source — git-tracked and untracked-but-not-gitignored files (via
git ls-files), or afindfallback in non-git dirs — and skips well-known vendored/build directories (node_modules,dist,build,vendor,.venv, caches, …). A stray*.rs/*.pyinsidenode_modules/or a build-output tree no longer flipsdetect_*totrue. A vendored tree that is committed and not gitignored is still seen as source; list it in a root.style-excludesfile (orSTYLE_EXTRA_EXCLUDES) to drop it from detection and linting. Seereferences/stack-detection.md. --hooksis opt-in. Hooks change commit behavior repo-wide. The installer always prints thegit commit --no-verifyescape.- Re-entrancy. Re-running the skill with
--syncon an already-installed target is a no-op for unchanged files, and prunes managed files removed upstream. Safe to schedule periodically. - Runtime-neutral aliases. When the target has no
package.json, the skill installs Makefile targets instead. Node is never required downstream. - Composing with
/init./init --formattersdelegates here and passes through--dry-runand--force. Invoke this skill directly for full flag coverage (CI, hooks, per-stack overrides). - For per-language tool rationale (why biome over eslint, ruff over flake8, etc.), see
references/best-practices.md.
Support files
Pointers below are conditional reads, not extra execution steps. Helpers consume templates automatically.
- Read
references/templates/package-json-scripts.json.tmpl,references/templates/makefile-snippet.mk.tmpl, andreferences/templates/justfile-snippet.just.tmplwhen inspecting alias output for package.json, Makefile, or justfile respectively. - Read
references/templates/readme-section.md.tmplwhen inspecting generated documentation (--no-docsskips it). - Read
references/templates/lint.yml.tmplwhen inspecting--cicheck output; readreferences/templates/lint-autofix.yml.tmplwhen--cienables autofix (not--no-autofix). - Read
references/templates/lefthook.yml.tmplwhen inspecting lefthook output; readreferences/templates/husky-pre-commit.tmplwhen inspecting Husky output under--hooks. - Run
scripts/bundle/style.shwhen installing/syncing the bundle in Phase 4. Readscripts/bundle/init-formatters.shwhen inspecting its install behavior;style.shruns it, do not run it separately. - Read
scripts/bundle/format.shandscripts/bundle/lint.shwhen inspecting installed format/lint dispatch; downstreamstyle.shruns them, do not run them separately here. - Read
scripts/bundle/go-tools.shwhen inspecting Go tool setup; readscripts/bundle/install-shellcheck.shwhen inspecting pinned ShellCheck setup. Installer/dispatcher runs them as needed; do not run them separately here. - Read
scripts/bundle/lib/excludes.shwhen inspecting ignore rules andscripts/bundle/lib/modified-files.shwhen inspecting changed-file selection. Sourceable helpers, not standalone commands. - Read
scripts/bundle/lib/shellcheck-resolve.shwhen inspecting ShellCheck lookup andscripts/bundle/lib/shellcheck-version.shwhen inspecting its pinned version. Sourceable helpers, not standalone commands. - Read
scripts/bundle/templates/biome.jsonandscripts/bundle/templates/tsconfig.jsonwhen inspecting TypeScript/JavaScript config output. - Read
scripts/bundle/templates/clippy.tomlandscripts/bundle/templates/rustfmt.tomlwhen inspecting Rust config output. - Read
scripts/bundle/templates/python-pyproject.tomlwhen inspecting Python config output. - Read
scripts/bundle/templates/markdownlint.json,scripts/bundle/templates/markdownlintignore,scripts/bundle/templates/prettierrc.json, andscripts/bundle/templates/prettierignorewhen inspecting docs config output.