Getting Started

Minimal Steps to First Use

Install via Laravel Boost (recommended for Laravel projects):
```
composer require spatie/guidelines-skills --dev
php artisan boost:install
```
- Select "Spatie guidelines" from the list during installation.
- Verify with php artisan boost:skills to confirm activation.
Install via skills.sh (for non-Laravel or CLI-focused workflows):
```
npx skills add spatie/guidelines-skills
```
- Test with npx skills lint to validate setup.
First Use Case: Enforce PHP/Laravel Standards
- Open a Laravel project in VS Code/PhpStorm with Laravel Boost installed.
- Write a new controller method (e.g., UserController@store).
- Observe real-time feedback for:
  - Naming conventions (e.g., snake_case for DB columns).
  - Control flow (e.g., prefer if (!empty($var)) over if ($var)).
  - Security (e.g., flagging mysql_query()).

Where to Look First

Configuration: .boost/skills.json (for Laravel Boost) or skills.config.js (for skills.sh). Example:

{
  "skills": {
    "spatie-laravel-php": {
      "enabled": true,
      "strict": true
    },
    "spatie-security": {
      "enabled": true,
      "rules": {
        "no-mysql-query": "error"
      }
    }
  }
}

Human-Readable Guidelines: spatie.be/guidelines (for context on rules).
CLI Commands:
- php artisan boost:skills (list/manage skills).
- npx skills lint (run checks manually).

Implementation Patterns

Core Workflows

1. Onboarding New Developers

Pattern: Use spatie-laravel-php and spatie-version-control to standardize:
- Code Structure: Enforce PSR-12 (e.g., use statements, method naming).
- Git Workflows: Auto-reject commits without conventional messages (e.g., feat:, fix:).
Workflow:
1. Add to composer.json:
```
"require-dev": {
  "spatie/guidelines-skills": "^1.0"
}
```
2. Configure .boost/skills.json to enable spatie-version-control with strict: true.
3. Train team to use git commit with Conventional Commits.

Pro Tip: Pair with a README.md snippet like:

## Coding Guidelines
This project enforces [Spatie’s Laravel/PHP guidelines](https://spatie.be/guidelines).
Run `php artisan boost:skills` to see active rules.

2. Security Hardening

Pattern: Layer spatie-security with Laravel’s built-in tools.
- Example Rules Enforced:
  - Reject mysql_query(), exec(), or eval().
  - Flag hardcoded secrets (e.g., config('services.stripe.key')).
  - Enforce CSRF protection in forms.
Workflow:
1. Enable in .boost/skills.json:
```
"spatie-security": {
  "enabled": true,
  "rules": {
    "no-hardcoded-secrets": "error",
    "use-csrf": "warning"
  }
}
```
2. Integrate with Laravel’s verify-csrf-token middleware for forms.
3. Use php artisan boost:skills:test to validate security checks in CI.

3. JavaScript/TypeScript Alignment

Pattern: Standardize frontend code with spatie-javascript.
- Key Rules:
  - Prettier formatting (e.g., single quotes, no semicolons).
  - Function naming (e.g., camelCase for methods).
  - Destructuring conventions.
Workflow:
1. Add to package.json:
```
"devDependencies": {
  "spatie/guidelines-skills": "^1.0"
}
```
2. Configure skills.sh to auto-fix:
```
npx skills add spatie-javascript --fix
```
3. Extend with ESLint for project-specific rules (e.g., @typescript-eslint).

4. CI/CD Integration

Pattern: Fail builds on guideline violations.

Example GitHub Actions Workflow:

name: Linting
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npx skills lint

Pro Tip: Use spatie-version-control to block non-compliant commits:

- run: |
    git diff --cached | npx skills check --skill spatie-version-control
    [ $? -ne 0 ] && echo "::error::Commit message must follow conventions." && exit 1

Integration Tips

With Laravel Boost:

Use php artisan boost:skills:test to validate all skills before merging.

Customize rules in .boost/skills.json:

"spatie-laravel-php": {
  "rules": {
    "naming": {
      "methods": "snake_case"  // Override default camelCase
    }
  }
}

With skills.sh:
- Run npx skills add spatie/guidelines-skills --all to enable all skills at once.
- Use npx skills lint --skill spatie-security to target specific checks.
With Existing Linters:
- PHP: Combine with php-cs-fixer or PHPStan for deeper analysis.
- JavaScript: Merge with ESLint by configuring skills.sh to run ESLint first, then Spatie’s rules.
- Git Hooks: Use spatie-version-control to reject commits with:
```
npx skills check --skill spatie-version-control
```

Gotchas and Tips

Pitfalls

Overriding Rules Without Awareness
- Issue: Disabling spatie-security rules (e.g., no-mysql-query) without compensating with Laravel’s security features (e.g., Query Builder).
- Fix: Document overrides in README.md:
```
## Security Overrides
Rule `no-mysql-query` is disabled for legacy `User` model. Use `DB::select()` instead.
```
Performance Impact in Large Codebases
- Issue: Running npx skills lint on a monorepo with 10K+ files may be slow.
- Fix: Use --path to target specific directories:
```
npx skills lint --path app/Http/Controllers
```
Conflicts with Custom Conventions
- Issue: Team uses PascalCase for controllers, but spatie-laravel-php enforces snake_case.
- Fix: Override in .boost/skills.json:
```
"spatie-laravel-php": {
  "rules": {
    "naming": {
      "controllers": "PascalCase"
    }
  }
}
```
False Positives in Legacy Code
- Issue: spatie-security flags mysql_query() in legacy code that’s already refactored.
- Fix: Use .boost/ignore.json to exclude files:
```
{
  "ignoredFiles": [
    "app/OldLegacyClass.php"
  ]
}
```
Skills.sh vs. Laravel Boost Conflicts
- Issue: Mixing skills.sh and Laravel Boost may lead to duplicate configurations.
- Fix: Stick to one system per project. Use Laravel Boost for Laravel projects; skills.sh for polyglot or CLI-heavy workflows.

Debugging Tips

Check Active Skills:

php artisan boost:skills  # Laravel Boost
npx skills list           # skills.sh

Run a Single Skill:

npx skills lint --skill spatie-security

View Rule Details:
- For Laravel Boost: php artisan boost:skills:show spatie-laravel-php.
- For skills.sh: Check the Spatie Guidelines docs for rule explanations.

Extension Points

Custom Skills
- Extend Spatie’s guidelines by creating

Guidelines Skills Laravel Package