Formatter Linter Expert

Formatter & Linter Expert Analyzer

Overview

A comprehensive, intelligent meta-formatter and linter system that automatically detects your project's ecosystem, respects asdf version management, and provides flexible formatting/linting workflows across 9+ development environments.

When to use this skill:

• "Analyze and format this Laravel project"
• "Lint my TypeScript code"
• "Check code style of this Go file"
• "Format all PHP files with Pint"
• "Quality report for this codebase"
• "Run formatter on src/ directory"
• "Interactive code cleanup"

What it does:

1. Detects ecosystem automatically (Laravel, Bun/Node, Go, Rust, Deno, etc.)
2. Integrates with asdf to use project-specific tool versions from .tool-versions
3. Finds configurations (auto-detect or use custom configs)
4. Analyzes OR formats code based on your choice
5. Generates comprehensive reports (Markdown + JSON export)
6. Interactive mode for file-by-file review and approval

Supported Ecosystems

Prerequisites

Required:

• Python 3.9+ (for skill scripts)
• Ecosystem-specific tools installed (see below)

Optional but Recommended:

• asdf version manager (installation guide)
• .tool-versions file in your project root

Ecosystem-specific tools:

• PHP: composer global require laravel/pint, composer global require friendsofphp/php-cs-fixer
• JavaScript/TypeScript: npm install -g prettier eslint @biomejs/biome or bun add -g prettier eslint @biomejs/biome
• Go: go install golang.org/x/tools/cmd/goimports@latest, go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
• Rust: rustfmt and clippy (included with rustup)
• Deno: deno cli (includes fmt and lint)

Instructions

Step 1: Invoke the Skill

Activate the skill naturally:

"Analyze this Laravel project"
"Format all TypeScript files"
"Lint and report on src/ directory"
"Interactive format for Go code"

Step 2: Environment Detection

The skill will automatically:

1. Search for .tool-versions (asdf integration)

   # Reads versions from current dir up to $HOME
   php 8.2.0
   nodejs 20.10.0
   golang 1.21.0
   

2. Detect ecosystem via file markers:

   • composer.json + artisan → Laravel
   • package.json + bun.lockb → Bun/*
   • go.mod → Go
   • Cargo.toml → Rust
   • deno.json → Deno

3. Find framework (if JavaScript/TypeScript):

   • Check package.json dependencies for react, vue, astro, nuxt

4. Locate configurations:

   • Auto-detect: pint.json, .eslintrc, .prettierrc, etc.
   • Custom: User can provide path
   • Fallback: Use skill's default configs

Step 3: Choose Operation Mode

Mode A: Analyze Only (default if ambiguous)

Generate comprehensive report WITHOUT modifying files
→ Ideal for CI/CD, code review, initial assessment

Mode B: Format (apply fixes directly)

Auto-fix all formatting issues
→ Fast, non-interactive, writes changes

Mode C: Interactive

Review and approve changes file-by-file
→ Safe, controlled, educational

Step 4: Execute Analysis/Formatting

The skill orchestrates:

# Pseudo-workflow
python scripts/main.py \
  --mode analyze \
  --scope project \
  --asdf-strict \
  --output markdown \
  --export-json report.json

Behind the scenes:

1. Environment detection runs first
2. Version validation checks asdf versions match
3. Config resolution finds or uses defaults
4. Formatter/Linter execution runs ecosystem tools
5. Report generation creates output

Step 5: Review Output

Analyze mode output:

# Code Quality Report

**Project:** my-laravel-app
**Environment:** Laravel 12 (PHP 8.2.0)
**Date:** 2025-10-30 14:23:45

## Summary
- Files analyzed: 127
- Issues found: 42
  - 🔴 Errors: 5
  - 🟡 Warnings: 15
  - 🔵 Info: 22

## Issues by Category
[Detailed breakdown...]

## Configuration Used
- Formatter: Laravel Pint
- Config: pint.json (detected)
- PHP Version: 8.2.0 (asdf)

## Recommendations
[Actionable next steps...]

Interactive mode prompt:

File: src/Controllers/UserController.php
Issues: 5 formatting, 2 linting

Preview of changes:
[diff display]

Apply fixes to this file? [y/n/s(kip)/q(uit)]: _

Step 6: Handle Multiple Ecosystems

If multiple ecosystems detected (e.g., Laravel backend + Vue frontend):

🔍 Detected multiple ecosystems:
  1. Laravel/PHP (app/, routes/, database/)
  2. Vue.js (resources/js/)

→ Formatting BOTH ecosystems...

[Run PHP formatters on PHP files]
[Run JS formatters on JS/Vue files]

Error Handling

Common Issues

asdf Integration Modes

Strict mode (default):

# Uses ONLY asdf versions, fails if not installed
--asdf-strict

Fallback mode:

# Tries asdf, falls back to system PATH if unavailable
--asdf-fallback

Report mode:

# Warns about version mismatch but continues
--asdf-warn

Examples

Example 1: Analyze Laravel Project

Input:

User: "Analyze and generate quality report for this Laravel API"

Execution:

# Skill detects:
# - Laravel 12 (composer.json + artisan)
# - PHP 8.2.0 from .tool-versions
# - Existing pint.json config

# Runs:
vendor/bin/pint --test --config pint.json
vendor/bin/phpstan analyze --level 5

# Outputs:
# report.md (detailed analysis)
# report.json (structured data)

Expected Output: Markdown report + JSON file showing 127 files analyzed, 42 issues categorized by severity.

Example 2: Format TypeScript with Biome

Input:

User: "Format all TypeScript files using Biome"

Execution:

# Skill detects:
# - TypeScript project (package.json with typescript dep)
# - Node 20.10.0 from .tool-versions
# - biome.json config present

# Runs:
biome format --write src/

# Outputs:
# Console: "✅ Formatted 45 files"

Example 3: Interactive Go Formatting

Input:

User: "Interactive format for Go files in cmd/ directory"

Execution:

# Skill detects:
# - Go project (go.mod)
# - Go 1.21.0 from .tool-versions
# - No config (uses defaults)

# Runs interactively:
# For each .go file:
#   - Shows gofmt diff
#   - Prompts: Apply? [y/n/s/q]
#   - Applies only if 'y'

Interactive Flow:

File: cmd/server/main.go (3 formatting issues)

--- Original
+++ Formatted
@@ -15,7 +15,7 @@
-func main(){
+func main() {

Apply fixes? [y/n/s/q]: y
✅ Applied

File: cmd/worker/worker.go (1 issue)
[...]

Example 4: Multi-Ecosystem Project (Laravel + Vue)

Input:

User: "Full project format - both backend and frontend"

Execution:

# Skill detects:
# - Laravel (composer.json)
# - Vue.js (package.json with vue dependency)
# - PHP 8.2.0 + Node 20.10.0 from .tool-versions

# Runs sequentially:
# 1. PHP formatting (Pint on app/, routes/, database/)
# 2. Vue formatting (Prettier on resources/js/)

# Outputs:
# Combined report for both ecosystems

Output:

# Multi-Ecosystem Report

## PHP (Laravel)
- Files: 87
- Fixed: 12 formatting issues

## JavaScript (Vue)
- Files: 40
- Fixed: 8 formatting issues

Total: 127 files processed, 20 issues fixed

Advanced Usage

Custom Configuration Path

User: "Format with custom config at configs/my-pint.json"

Skill will use --config configs/my-pint.json flag.

Specific File/Directory Scope

User: "Lint only the app/Services/ directory"

Skill scopes analysis to that path only.

Export JSON for CI/CD

User: "Generate JSON report for pipeline"

Outputs report.json:

{
  "project": "my-app",
  "timestamp": "2025-10-30T14:23:45Z",
  "environment": {
    "ecosystem": "laravel",
    "php_version": "8.2.0",
    "tools": ["pint", "phpstan"]
  },
  "summary": {
    "files_analyzed": 127,
    "issues": {
      "errors": 5,
      "warnings": 15,
      "info": 22
    }
  },
  "issues": [
    {
      "file": "app/Http/Controllers/UserController.php",
      "line": 45,
      "severity": "error",
      "message": "Indentation incorrect",
      "rule": "PSR-12"
    }
  ],
  "exit_code": 1
}

Best Practices

✅ Do This

1. Use asdf for version consistency across team
2. Commit configs (.prettierrc, pint.json) to version control
3. Run analyze first before formatting to understand impact
4. Use interactive mode when learning or unsure about changes
5. Export JSON for integration with CI/CD pipelines
6. Check exit codes in scripts (0 = clean, >0 = issues found)

⚠️ Avoid This

1. Don't skip analyze - Always review before mass formatting
2. Don't ignore version mismatches - Formatting can vary between tool versions
3. Don't mix formatters - Pick one (Prettier vs Biome) and stick with it
4. Don't format generated code - Exclude vendor/, node_modules/, dist/
5. Don't commit without testing - Run tests after formatting

Troubleshooting

Issue: "No ecosystem detected"

Cause: Project lacks recognizable file markers

Fix:

# Manual specification
User: "Format this PHP project using Pint"
# Or create marker file
touch composer.json  # for PHP projects

Issue: "asdf: command not found"

Cause: asdf not installed or not in PATH

Fix:

# Install asdf
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0

# Add to shell
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
source ~/.bashrc

# Or use fallback mode
User: "Format with system tools (ignore asdf)"

Issue: "Version mismatch: PHP 8.2.0 not installed"

Cause: .tool-versions specifies version not installed via asdf

Fix:

# Install missing version
asdf plugin add php
asdf install php 8.2.0

# Or use fallback mode to use system PHP

Issue: "Config parsing error: Invalid JSON in biome.json"

Cause: Malformed configuration file

Fix:

# Validate JSON
cat biome.json | jq .

# Or use default config
User: "Format using default Biome config"

Technical Details

Architecture

User Request
    ↓
Environment Detector
    ├─ asdf Manager (version resolution)
    ├─ Config Finder (locate configs)
    └─ File Analyzer (detect ecosystem)
    ↓
Orchestrator
    ├─ PHP Formatter/Linter
    ├─ JS Formatter/Linter
    ├─ Go Formatter/Linter
    ├─ Rust Formatter/Linter
    └─ Deno Formatter/Linter
    ↓
Reporter
    ├─ Markdown Report
    ├─ JSON Export
    └─ Console Output

Token Efficiency

• Metadata load: ~500 tokens (always loaded in context)
• Full instructions (this file): ~3,500 tokens (loaded on activation)
• Script execution: 0 tokens (Python runs externally, only output returned)
• Total skill overhead: ~4,000 tokens

Performance Considerations

• Small projects (<100 files): ~5-10 seconds
• Medium projects (100-500 files): ~30-60 seconds
• Large projects (>500 files): 1-3 minutes

Optimization tips:

• Use --scope to limit analysis to specific directories
• Exclude large directories with --exclude node_modules,vendor
• Run formatters in parallel for multi-ecosystem projects

Exit Codes

Related Skills

No related skills detected in current environment

Maintenance

Version History:

• v1.0.0 (2025-10-30) - Initial release with 9 ecosystem support

Roadmap:

• Add Python support (black, ruff)
• Add Swift support (swift-format)
• Add Kotlin support (ktlint)
• GitHub Actions integration
• VS Code extension

Known Limitations:

• Requires tools to be pre-installed (doesn't auto-install)
• asdf integration tested on Unix-like systems only
• Interactive mode not suitable for CI/CD pipelines

Author: Created for personal cross-project use Created: 2025-10-30 License: Personal use

Quick Command Reference

# Analyze only (default)
"Analyze this project"

# Format directly
"Format all files"

# Interactive review
"Interactive format"

# Specific scope
"Lint the src/ directory"
"Format app/Services/PaymentService.php"

# Custom config
"Format using my custom Pint config at config/pint.json"

# Export report
"Generate quality report with JSON export"

# Multi-ecosystem
"Format both PHP and Vue code"

# Ignore asdf
"Format using system tools"

Need Help?

• Check tool installation: which pint, which prettier, etc.
• Verify asdf setup: asdf current
• Review config files: cat pint.json, cat .eslintrc
• Test manually: vendor/bin/pint --test, prettier --check src/