The Complete Production SOP: How to Deploy and Run SQLFluff Modular SQL Linter & Auto-Formatter in Autonomous AI Agents
Step-by-step SOP to install and run SQLFluff Modular SQL Linter in Codex, Claude Code, and Cursor. Fix dbt SQL formatting errors deterministically with AI agents.
Technical Overview & Architectural Context
Autonomous coding agents frequently generate inconsistent, dialect-violating SQL when modifying data models across heterogeneous stacks (Snowflake, BigQuery, Postgres, dbt). Without strict guardrails, agents introduce subtle formatting regressions, unescaped reserved keywords, mixed-case identifiers, and syntax incompatibilities with Jinja-templated macros. These subtle discrepancies lead to broken pre-commit hooks, failed data pipeline builds, and expensive compute failures in target data warehouses. The SQLFluff Modular SQL Linter & Auto-Formatter skill provides a deterministic procedural boundary for coding assistants like Codex Desktop, Claude Code, Cursor, and Windsurf. By constraining agent behaviors to verified configuration templates (.sqlfluff), enforcing strict dialect validation, and providing deterministic remediation loops (sqlfluff lint -> fix -> verify), the skill ensures that all model changes strictly adhere to architectural styling and dialect-specific AST rules before pushing commits.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into agent runtime contexts.
Autonomous agent frameworks like Claude Code and Cursor scan local skill paths (~/.agents/skills or workspace-specific .agent/skills) to load procedural triggers. Placing the SKILL.md manifest into the target registry enables the runtime to index exact triggers like 'lint sql with sqlfluff' and match user intent with near-zero latency.
mkdir -p ~/.agents/skills/sqlfluff-modular-sql-linter && curl -fsSL https://askills.dev/api/skills/sqlfluff-modular-sql-linter/raw -o ~/.agents/skills/sqlfluff-modular-sql-linter/SKILL.md---
name: "sqlfluff-modular-sql-linter"
description: "Enforce consistent SQL styling, capitalizations, and dialect rules across large teams."
metadata:
author: "SQLFluff"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "lint sql with sqlfluff"
- "fix sql formatting sqlfluff"
- "configure .sqlfluff dialect"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# SQLFluff Modular SQL Linter & Auto-Formatter
Configures SQLFluff: setting dialect (snowflake, bigquery, postgres, mysql), linting complex jinja/dbt templates, tuning rule sets, and executing fixes.
## Execution SOP & Rules
1. Ensure a valid `.sqlfluff` exists at project root.
2. Execute `sqlfluff lint <path> --format human` to surface AST and rule violations.
3. Execute `sqlfluff fix <path> --force` to apply deterministic AST corrections.
4. Re-run `sqlfluff lint <path>` to confirm 0 errors before closing the task.Mount the skill globally in ~/.agents/skills or link directly to .cursor/rules/sqlfluff.md to ensure all workspace sessions load dialect rules without token-heavy preamble prompts.
Ensure directory permissions on ~/.agents/skills are set to 0755; some containerized agent runners run as non-root users and fail silently if skill manifests are unreadable.
Environment Secrets & Dependency Validation
Verify the SQLFluff executable and required dialect plugins inside the local Python runtime.
SQLFluff requires dialect-aware parser plugins (such as sqlfluff-templater-dbt) to interpret macro syntax. The agent must verify that Python has the correct packages installed without exposing warehouse connection secrets or passing credentials over unauthenticated channels.
uv pip install 'sqlfluff>=3.0.0' 'sqlfluff-templater-dbt>=3.0.0' && sqlfluff --version[sqlfluff]
dialect = snowflake
templater = dbt
runaway_limit = 10
max_line_length = 100
indent_unit = space
[sqlfluff:indentation]
indented_joins = false
tab_space_size = 4
[sqlfluff:rules:capitalisation.keywords]
capitalisation_policy = upper
[sqlfluff:rules:capitalisation.identifiers]
capitalisation_policy = lower
[sqlfluff:templater:dbt]
project_dir = ./
profiles_dir = ~/.dbt
profile = analyticsSpecify 'runaway_limit = 10' in .sqlfluff to prevent recursive macro evaluation loops from burning agent compute tokens and hanging CLI subshells.
Never write database credentials into the project root .sqlfluff. Ensure profiles_dir points to an external secrets directory like ~/.dbt or leverages environment variables.
Intent Matching & Trigger Invocation
Activate the deterministic SQL linting workflow using natural language triggers.
Modern agent parsers evaluate user prompts against the trigger patterns declared in SKILL.md. By commanding 'lint sql with sqlfluff' or 'fix sql formatting sqlfluff', the agent switches context from speculative text generation to deterministic AST linting SOP execution.
claude 'fix sql formatting sqlfluff on models/staging/stg_stripe__payments.sql'#!/usr/bin/env bash
set -euo pipefail
TARGET_PATH="${1:-models/}"
echo "==> Running SQLFluff Lint on ${TARGET_PATH}"
sqlfluff lint "${TARGET_PATH}" --dialect snowflake --ignore parsing,templating
echo "==> Applying Auto-Fixes"
sqlfluff fix "${TARGET_PATH}" --dialect snowflake --force --rules capitalisation.keywords,capitalisation.identifiers,layout.spacingTarget specific modified files or directories rather than running sqlfluff across the entire repository to keep diff outputs concise and minimize agent token usage.
Avoid using the '--force' flag in untracked git trees; unstaged manual edits could be overwritten without an easy rollback path.
Verification, Linting & Output Quality Gate
Run an automated self-healing audit loop before marking model changes as resolved.
The skill mandates that the agent execute a final verification step. If violations persist after running 'sqlfluff fix', the agent must inspect the remaining errors (e.g., CP01 for capitalization conflicts, AM04 for ambiguous column names) and manually repair the SQL AST before finalizing the response.
sqlfluff lint models/ --dialect snowflake --format json > lint_report.json && jq length lint_report.json#!/usr/bin/env bash
set -eo pipefail
EXIT_CODE=0
sqlfluff lint models/ || EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
echo "Quality gate failed: SQLFluff discovered non-compliant queries."
exit 1
else
echo "Quality gate passed: All SQL models conform to style specifications."
exit 0
fiInstruct the agent to inspect git diff immediately following 'sqlfluff fix' to detect unintended formatting shifts in Jinja control blocks before running compile tests.
SQLFluff fix may fail on structural Jinja indentation if mixed tabs and spaces are used. Ensure indentation rules match dbt compiler expectations.
Real-World Scenario: Automated Remediation of Snowflake dbt Models in Production Repo
“lint sql with sqlfluff in models/marts/finance/ and fix all keyword capitalizations and trailing whitespace violations according to our .sqlfluff rules.”
Runtime Troubleshooting & Failure Modes
Root Cause: SQLFluff is configured with the raw SQL parser rather than the dbt templater, preventing Jinja expression evaluation.
uv pip install sqlfluff-templater-dbt && sed -i '' 's/templater = raw/templater = dbt/g' .sqlfluffRoot Cause: The agent executed sqlfluff inside an isolated sandbox where the user profile directory was unmounted or DBT_PROFILES_DIR was unset.
export DBT_PROFILES_DIR="$(pwd)" && sqlfluff lint models/ --templater dbt --dialect snowflakeFrequently Asked Questions (SQLFluff Modular SQL Linter & Auto-Formatter SOP)
Q:Can I use SQLFluff Modular SQL Linter & Auto-Formatter across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification supported across all modern agent runtimes. Simply mount it in your global skills directory or within the project root repository.
Q:How does SQLFluff Modular SQL Linter & Auto-Formatter prevent context window overflow during long agent sessions?
By constraining agent interactions to targeted CLI invocations and JSON/diff summary formats rather than outputting entire raw SQL files into the conversational context window.
Q:Does this skill require escalated root or container permissions?
No. It is audited with a security score of 98/100, requiring only workspace-level filesystem reads/writes and Python execution permissions within standard user sandboxes.
Ready to equip your autonomous agent with SQLFluff Modular SQL Linter & Auto-Formatter?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.