Skill: Code Formatting

When to Use This Skill

This skill activates when you need to:

• Format code to match project style guidelines
• Fix linting errors
• Set up automatic code formatting
• Understand project formatting standards

Prerequisites

Check project for existing formatting configuration:

• .prettierrc, .eslintrc (JavaScript/TypeScript)
• .black, pyproject.toml, ruff.toml (Python)
• .rustfmt.toml (Rust)
• .gofmt settings (Go)

Step-by-Step Workflow

Step 1: Detect Formatting Tools

Check {{lint_command}} or look for:

• package.json scripts: "format", "lint", "lint:fix"
• Configuration files in project root
• .pre-commit-config.yaml for pre-commit hooks
• CI/CD workflows for formatting checks

Step 2: Format Code by Tech Stack

Python

Option A: Black (Opinionated)

# Install
pip install black

# Format all Python files
black .

# Format specific file
black myfile.py

# Check without modifying
black --check .

# Preview changes
black --diff .

Add to pyproject.toml:

[tool.black]
line-length = 88
target-version = ['py310']
include = '\.pyi?$'
extend-exclude = '''
/(
  # directories
  \.eggs
  | \.git
  | \.venv
  | build
  | dist
)/
'''

Option B: Ruff (Fast, Modern)

# Install
pip install ruff

# Format code
ruff format .

# Check and fix linting
ruff check --fix .

# Check only
ruff check .

Add ruff.toml:

line-length = 88
target-version = "py310"

[lint]
select = ["E", "F", "I", "N", "W"]
ignore = ["E501"]

[format]
quote-style = "double"
indent-style = "space"

Option C: autopep8

# Install
pip install autopep8

# Format file
autopep8 --in-place --aggressive --aggressive myfile.py

# Format all files
find . -name '*.py' -exec autopep8 --in-place --aggressive --aggressive {} \;

JavaScript/TypeScript

Option A: Prettier

# Install
npm install --save-dev prettier

# Format all files
npx prettier --write .

# Format specific files
npx prettier --write "src/**/*.{js,jsx,ts,tsx,json,css,md}"

# Check formatting
npx prettier --check .

Add .prettierrc:

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false
}

Option B: ESLint (with autofix)

# Install
npm install --save-dev eslint

# Fix all fixable issues
npx eslint --fix .

# Fix specific files
npx eslint --fix src/**/*.js

Combined (Prettier + ESLint):

# Format with Prettier, then lint with ESLint
npx prettier --write . && npx eslint --fix .

Add to package.json:

{
  "scripts": {
    "format": "prettier --write .",
    "lint": "eslint .",
    "lint:fix": "eslint --fix ."
  }
}

Go

Built-in gofmt:

# Format all Go files
gofmt -w .

# Format specific file
gofmt -w main.go

# Check formatting (returns files that need formatting)
gofmt -l .

Alternative: goimports (adds/removes imports)

# Install
go install golang.org/x/tools/cmd/goimports@latest

# Format and fix imports
goimports -w .

Option: golangci-lint (comprehensive)

# Install
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run linters and auto-fix
golangci-lint run --fix

Rust

Built-in rustfmt:

# Format all Rust files
cargo fmt

# Check formatting without modifying
cargo fmt -- --check

Add rustfmt.toml:

max_width = 100
hard_tabs = false
tab_spaces = 4
edition = "2021"

Clippy (Rust linter):

# Run Clippy
cargo clippy

# Auto-fix some issues
cargo clippy --fix

Ruby

RuboCop:

# Install
gem install rubocop

# Auto-fix
rubocop -A

# Check only
rubocop

# Fix safe issues only
rubocop --safe-auto-correct

Add .rubocop.yml:

AllCops:
  TargetRubyVersion: 3.0
  NewCops: enable

Style/StringLiterals:
  EnforcedStyle: single_quotes

Java

Google Java Format:

# Download
wget https://github.com/google/google-java-format/releases/download/v1.17.0/google-java-format-1.17.0-all-deps.jar

# Format file
java -jar google-java-format-1.17.0-all-deps.jar -i MyFile.java

# Format all Java files
find . -name "*.java" -exec java -jar google-java-format-1.17.0-all-deps.jar -i {} \;

Step 3: Set Up Automatic Formatting

VS Code

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[go]": {
    "editor.formatOnSave": true
  }
}

Pre-commit Hooks

Install pre-commit:

pip install pre-commit

Create .pre-commit-config.yaml:

For Python:

repos:
  - repo: https://github.com/psf/black
    rev: 23.7.0
    hooks:
      - id: black
  - repo: https://github.com/charliermarsh/ruff-pre-commit
    rev: v0.0.280
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]

For JavaScript/TypeScript:

repos:
  - repo: https://github.com/pre-commit/mirrors-prettier
    rev: v3.0.0
    hooks:
      - id: prettier
        types_or: [javascript, jsx, ts, tsx, json, css, markdown]
  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v8.44.0
    hooks:
      - id: eslint
        args: [--fix]

Install hooks:

pre-commit install

Run on all files:

pre-commit run --all-files

Step 4: Check Formatting in CI

GitHub Actions example (.github/workflows/format-check.yml):

Python:

name: Format Check
on: [push, pull_request]
jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - run: pip install black ruff
      - run: black --check .
      - run: ruff check .

JavaScript:

name: Format Check
on: [push, pull_request]
jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run lint
      - run: npx prettier --check .

Common Issues and Solutions

Issue: Formatter not found or command fails

Solutions:

1. Install formatter: pip install black or npm install -D prettier
2. Check if it's in package.json/requirements.txt
3. Activate virtual environment (Python)
4. Clear npm cache: npm cache clean --force

Issue: Formatting conflicts between tools

Solutions:

1. Choose one primary formatter (Black/Prettier)
2. Configure linter to defer to formatter
3. Use prettier-eslint or eslint-config-prettier for JS
4. Disable formatting rules in linter config

Issue: Files keep getting reformatted back and forth

Solutions:

1. Ensure all developers use same formatter version
2. Commit .prettierrc, .black, etc. to repo
3. Run formatter in CI to enforce
4. Check for conflicting editor settings

Issue: Some files excluded from formatting

Solutions:

1. Check .prettierignore, .gitignore, exclude patterns
2. Verify file extensions are included
3. Check formatter configuration
4. Run with verbose flag to see what's excluded

Success Criteria

• ✅ Code formatted consistently across all files
• ✅ No formatting errors in output
• ✅ Linting errors fixed or documented
• ✅ Format-on-save configured (optional)
• ✅ Pre-commit hooks working (optional)

Quick Reference Commands

Related Skills

• local-dev-setup - Initial project setup
• git-workflow - Git pre-commit integration
• ci-pipeline - CI formatting checks

Documentation References

• Black Documentation
• Ruff Documentation
• Prettier Documentation
• ESLint Documentation
• pre-commit