Linting and Code Quality Skill Skill

Linting and Code Quality Skill

This skill helps you efficiently validate and format code using the project's comprehensive linting infrastructure.

When to Use This Skill

Use this skill when you:

Edit a file and want to format it before committing
Need to validate code style, types, or security
Want to check for spelling errors or documentation issues
Need to validate test infrastructure (suitespec, log messages)
Want to run comprehensive quality checks before pushing

Key Principles

Always format after editing - Use hatch run lint:fmt -- <file> immediately after code changes
Run comprehensive checks before committing - Use hatch run lint:checks before pushing
Target specific files - Use -- <file> syntax to validate only what you changed, not the entire codebase
Fix auto-fixable issues - Use fmt instead of manually fixing style issues
Type check after adding types - Use hatch run lint:typing -- <file> after adding type annotations

Quick Start

Run all checks (broad validation):

hatch run lint:checks

Format and validate a specific file:

hatch run lint:fmt -- path/to/file.py

Check types on a specific file:

hatch run lint:typing -- path/to/file.py

Available Lint Scripts

Code Formatting

`fmt` - Format code (recommended for most edits)

Formats and validates code style using Ruff.

Usage:

# Format entire codebase
hatch run lint:fmt

# Format specific files
hatch run lint:fmt -- ddtrace/tracer.py tests/test_tracer.py

# Format specific directory
hatch run lint:fmt -- ddtrace/contrib/flask/

What it does:

Runs the Ruff formatter
Runs Ruff with --fix to auto-fix issues
Re-validates with style checks

When to use: After making code changes to automatically format and fix style issues.

`fmt-snapshots` - Format snapshot files

Formats snapshot test files used in snapshot-based testing.

Usage:

hatch run lint:fmt-snapshots -- tests/snapshots/

When to use: After snapshot test updates or when snapshot files need reformatting.

Style Checking

`style` - Check all style issues (no auto-fix)

Validates code style without automatically fixing issues.

Usage:

# Check entire codebase
hatch run lint:style

# Check specific files
hatch run lint:style -- ddtrace/

What it validates:

Ruff formatting
Ruff linting rules
Cython linting
C code formatting
CMake formatting

When to use: To verify style compliance before committing without auto-fixes.

`format_check` - Check formatting

Validates Python code formatting with ruff format (no auto-fix).

Usage:

hatch run lint:format_check -- ddtrace/tracer.py

When to use: Quick check of Python formatting before committing.

Type Checking

`typing` - Type check with mypy

Validates Python type hints and catches type-related errors.

Usage:

# Check all types
hatch run lint:typing

# Check specific files (mypy path format)
hatch run lint:typing -- ddtrace/tracer.py

When to use: After adding type hints or modifying functions with type annotations.

Security Checks

`security` - Security audit with Bandit

Scans code for common security issues and vulnerabilities.

Usage:

# Scan entire codebase
hatch run lint:security

# Scan specific directory
hatch run lint:security -- -r ddtrace/contrib/

When to use: Before committing code that handles user input, credentials, or sensitive operations.

Spelling and Documentation

`spelling` - Check spelling

Validates spelling in documentation, comments, and docstrings.

Usage:

# Check all spelling
hatch run lint:spelling

# Check specific files
hatch run lint:spelling -- docs/ releasenotes/

When to use: Before committing documentation or user-facing text.

Test Infrastructure

`riot` - Validate riotfile

Doctests the riotfile to ensure test venv definitions are valid.

Usage:

hatch run lint:riot

When to use: After modifying riotfile.py to validate syntax and doctest examples.

`suitespec-check` - Validate test suite specifications

Checks that test suite patterns in tests/suitespec.yml cover all test files.

Usage:

hatch run lint:suitespec-check

When to use: After adding new test files or modifying suite specifications.

`error-log-check` - Validate error log messages

Ensures error log messages follow project conventions.

Usage:

hatch run lint:error-log-check

When to use: After adding new error logging statements.

Code Analysis

`sg` - Static analysis with ast-grep

Performs static code analysis using ast-grep patterns.

Usage:

# Scan all files
hatch run lint:sg

# Scan specific directory
hatch run lint:sg -- ddtrace/

When to use: To find code patterns that may need refactoring or optimization.

`sg-test` - Test ast-grep rules

Validates ast-grep rule definitions.

Usage:

hatch run lint:sg-test

When to use: After modifying ast-grep rules or patterns.

C/CMake Formatting

`cformat_check` - Check C code formatting

Validates C code formatting.

Usage:

hatch run lint:cformat_check

When to use: After modifying C extension code.

`cmakeformat_check` - Check CMake formatting

Validates CMake file formatting.

Usage:

hatch run lint:cmakeformat_check

When to use: After modifying CMakeLists.txt or other CMake files.

Common Workflows

Workflow 1: Quick File Format and Check

After editing a Python file, format and validate it:

# Edit the file...
# Then run:
hatch run lint:fmt -- path/to/edited/file.py

Workflow 2: Type Check After Adding Types

After adding type hints:

hatch run lint:typing -- ddtrace/contrib/flask/patch.py

Workflow 3: Full Validation Before Commit

Run all checks before creating a commit:

hatch run lint:checks

This runs:

style checks
typing checks
spelling checks
riot validation
security checks
suitespec validation
error log validation
ast-grep analysis

Workflow 4: Security Review

Before committing code handling sensitive operations:

hatch run lint:security -- -r ddtrace/contrib/

Workflow 5: Documentation Review

After writing documentation or docstrings:

hatch run lint:spelling -- docs/ ddtrace/

Best Practices

DO ✅

Format files immediately after editing: Use hatch run lint:fmt -- <file> to auto-fix style issues
Run lint:checks before pushing: Ensures all quality gates pass
Target specific files: Use -- <file> syntax to validate only what you changed
Check types early: Run lint:typing after adding type annotations
Read error messages: Understand what lint failures mean before fixing

DON'T ❌

Ignore lint failures: They indicate potential bugs or style issues
Manually fix issues that auto-fix can handle: Use fmt instead
Commit without running lint:checks: Let automation catch issues before push
Run lint:checks every time for small changes: Use targeted commands during development

Passing Arguments

All lint commands support passing arguments with -- syntax:

# Basic format
hatch run lint:<script> -- <args>

# Examples:
hatch run lint:fmt -- ddtrace/tracer.py                    # Format specific file
hatch run lint:typing -- ddtrace/                           # Type check directory
hatch run lint:security -- -r ddtrace/contrib/              # Security scan with args
hatch run lint:spelling -- docs/ releasenotes/              # Spelling check specific paths

Troubleshooting

Formatting keeps failing

Ensure you've run hatch run lint:fmt to auto-fix style issues first:

hatch run lint:fmt -- <file>
hatch run lint:style -- <file>  # Should now pass

Type errors after editing

Make sure type hints are correct and all imports are available:

hatch run lint:typing -- <file>

Lint command not found

Ensure you're running from the project root:

cd /path/to/dd-trace-py
hatch run lint:checks

Too many errors to fix manually

Use fmt to auto-fix most issues:

hatch run lint:fmt -- .

run-tests skill: For validating that changes don't break tests
hatch.toml: Source of truth for all lint configurations
riotfile.py: Defines test venvs and combinations

Agent Skills: Linting and Code Quality Skill

Install this agent skill to your local

Skill Files