configure-formatting

# /configure:formatting Check and configure code formatting tools against modern best practices. ## When to Use This Skill | Use this skill when... | Use another approach when... | |------------------------|------------------------------| | Setting up Biome, Ruff format, or rustfmt for a project | Running an existing formatter (`biome format`, `ruff format`) | | Migrating from Prettier or ESLint to Biome, or Black to Ruff | Fixing individual formatting issues in specific files | | Auditing formatter configuration for completeness and best practices | Configuring linting rules (`/configure:linting` instead) | | Adding format-on-save and CI format checks | Setting up pre-commit hooks only (`/configure:pre-commit` instead) | | Standardizing formatting settings across a monorepo | Editing `.editorconfig` or `.vscode/settings.json` manually | ## Context - Biome config: !`find . -maxdepth 1 -name \'biome.json\'` - Prettier config: !`find . -maxdepth 1 \( -name '.prettierrc*' -o -name 'prettier.config.*' \)` - Ruff config: !`find . -maxdepth 1 -name 'pyproject.toml' -exec grep -l 'tool.ruff.format' {} +` - Black config: !`find . -maxdepth 1 -name 'pyproject.toml' -exec grep -l 'tool.black' {} +` - Rustfmt config: !`find . -maxdepth 1 \( -name 'rustfmt.toml' -o -name '.rustfmt.toml' \)` - EditorConfig: !`find . -maxdepth 1 -name \'.editorconfig\'` - Package JSON: !`find . -maxdepth 1 -name \'package.json\'` - Python project: !`find . -maxdepth 1 -name \'pyproject.toml\'` - Rust project: !`find . -maxdepth 1 -name \'Cargo.toml\'` - Pre-commit: !`find . -maxdepth 1 -name \'.pre-commit-config.yaml\'` - Project standards: !`find . -maxdepth 1 -name \'.project-standards.yaml\'` ## Parameters Parse from `$ARGUMENTS`: - `--check-only`: Report compliance status without modifications - `--fix`: Apply all fixes automatically without prompting - `--formatter <formatter>`: Override formatter detection (biome, ruff, rustfmt) ## Version Checking **CRITICAL**: Before flagging outdated formatters, verify latest releases using WebSearch or WebFetch: 1. **Biome**: Check [biomejs.dev](https://biomejs.dev/) or [GitHub releases](https://github.com/biomejs/biome/releases) 2. **Ruff**: Check [docs.astral.sh/ruff](https://docs.astral.sh/ruff/) or [GitHub releases](https://github.com/astral-sh/ruff/releases) 3. **rustfmt**: Bundled with Rust toolchain - check [Rust releases](https://releases.rs/) ## Execution Execute this code formatting configuration workflow: ### Step 1: Detect formatters and integration state Run the detection script to scan the project for formatter config files, script/hook/CI presence, and a recommendation over the detected booleans: ```bash bash "${CLAUDE_SKILL_DIR}/scripts/configure-formatting.sh" --home-dir "$HOME" --project-dir "$(pwd)" ``` Parse `STATUS=` and the `ISSUES:` block from the output. The `KEY=VALUE` lines report formatter detection (`BIOME`, `PRETTIER`, `RUFF_FORMAT`, `BLACK`, `RUSTFMT`, `EDITORCONFIG`), integration signals (`FORMAT_SCRIPT`, `PRE_COMMIT_FORMAT`, `CI_FORMAT`), and a `RECOMMENDATION` of `configured` (a modern formatter is set up), `migrate` (a legacy formatter wants migration to Biome/Ruff), or `setup` (no formatter detected). **How `CI_FORMAT` is decided.** The probe scans `.github/workflows/*.yml|yaml` for a command that runs the formatter, then resolves **one** level of package-script indirection: | Signal | `CI_FORMAT` | Why | |--------|-------------|-----| | Workflow runs `biome check` / `biome ci` | `true` | In Biome 2.x `check` is the combined command (formatter + linter + import sorting); `ci` is its CI-oriented variant | | Workflow runs `biome format`, `ruff format`, `cargo fmt`, `prettier` | `true` | Format-only commands, named directly | | Workflow runs `biome lint` | `false` | Lint-only — it does not format | | Workflow runs `bun run <s>` / `npm run <s>` / `pnpm run <s>` / `yarn <s>` and `package.json`'s `scripts.<s>` contains any command above | `true` | The idiomatic setup keeps the real command in `package.json` | | That script calls *another* script (depth 2+) | `false` | Exactly one level is resolved; deeper chains are out of scope | Indirection needs `jq` and a readable `package.json`. When `package.json` is absent, unparseable, or has no `scripts` key — or `jq` is unavailable — the lookup degrades silently to the direct-command scan (no stderr, exit 0). **Modern formatting preferences:** - **JavaScript/TypeScript**: Biome (replaces Prettier + ESLint). On `RECOMMENDATION=migrate` with Prettier present, offer migration to Biome — do not configure Prettier as the target formatter. - **Python**: Ruff format (replaces Black) - **Rust**: rustfmt (standard) ### Step 2: Generate compliance report Print a formatted compliance report: ``` Code Formatting Compliance Report ================================== Project: [name] Language: [detected] Formatter: [detected] Configuration: [status per check] Format Options: [status per check] Scripts: [status per check] Integration: [status per check] Overall: [X issues found] Recommendations: [list specific fixes] ``` If `--check-only`, stop here. ### Step 3: Install and configure formatter (if --fix or user confirms) Based on detected language and formatter preference, install and configure. Use configuration templates from [REFERENCE.md](REFERENCE.md). 1. Install formatter package 2. Create configuration file (biome.json, pyproject.toml section, rustfmt.toml) 3. Add format scripts to package.json or Makefile/justfile 4. Configure ignore patterns in the formatter config (e.g. `files.includes` in biome.json) ### Step 4: Create EditorConfig integration Create or update `.editorconfig` with settings matching the formatter configuration. ### Step 5: Handle migrations (if applicable) If legacy formatter detected (Prettier -> Biome, Black -> Ruff): 1. Import existing configuration 2. Install new formatter 3. Remove old formatter 4. Update scripts 5. Update pre-commit hooks Use migration guides from [REFERENCE.md](REFERENCE.md). ### Step 6: Configure pre-commit hooks Add formatter to `.pre-commit-config.yaml` using the appropriate hook repository. ### Step 7: Configure CI/CD integration Add format check step to GitHub Actions workflow. ### Step 8: Configure editor integration Create or update `.vscode/settings.json` with format-on-save and `.vscode/extensions.json` with formatter extension. ### Step 9: Update standards tracking Update `.project-standards.yaml`: ```yaml components: formatting: "2025.1" formatting_tool: "[biome|ruff|rustfmt]" formatting_pre_commit: true formatting_ci: true ``` ### Step 10: Print completion report Print a summary of changes made, scripts added, and next steps (run format, verify CI, enable format-on-save). For detailed configuration templates, migration guides, and pre-commit configurations, see [REFERENCE.md](REFERENCE.md). ## Agentic Optimizations | Context | Command | |---------|---------| | Quick compliance check | `/configure:formatting --check-only` | | Auto-fix all issues | `/configure:formatting --fix` | | Check Biome formatting | `biome format --check --reporter=github` | | Check Ruff formatting | `ruff format --check --output-format=github` | | Check rustfmt formatting | `cargo fmt --check 2>&1 | head -20` | ## Flags | Flag | Description | |------|-------------| | `--check-only` | Report status without offering fixes | | `--fix` | Apply all fixes automatically without prompting | | `--formatter <formatter>` | Override formatter detection (biome, ruff, rustfmt) | ## Examples ```bash # Check compliance and offer fixes /configure:formatting # Check only, no modifications /configure:formatting --check-only # Auto-fix and migrate to Biome /configure:formatting --fix --formatter biome ``` ## Error Handling - **Multiple formatters detected**: Warn about conflict, suggest migration - **No package manager found**: Cannot install formatter, error - **Invalid configuration**: Report parse error, offer to replace with template - **Formatting conflicts**: Report files that would be reformatted ## See Also - `/configure:linting` - Configure linting tools - `/configure:editor` - Configure editor settings - `/configure:pre-commit` - Pre-commit hook configuration - `/configure:all` - Run all compliance checks - **Biome documentation**: https://biomejs.dev - **Ruff documentation**: https://docs.astral.sh/ruff - **rustfmt documentation**: https://rust-lang.github.io/rustfmt