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

pint.json

.php-cs-fixer.php

phpstan.neon

.prettierrc

biome.json

.eslintrc*

.golangci.yml

rustfmt.toml

clippy.toml

deno.json

deno.jsonc

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

Tool not found: pint

composer global require laravel/pint

asdf version mismatch

.tool-versions

asdf install

No ecosystem detected

--env

Config parsing failed

--use-defaults

Permission denied

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

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

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/