Boost Skills Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require sandermuller/boost-skills
   

   • Contains Markdown-based skill catalog plus helper shell scripts for certain skills (e.g., resolve-conflicts/dangling-symbols.sh).
   • No PHP runtime dependencies, but some skills ship executable shell tooling that is invoked by the sync engine or manually.

2. Pair with a Sync Engine:

   • Requires sandermuller/boost-core or laravel/boost to sync skills to your AI agent (e.g., Claude, Cursor, Copilot).
   • Example with Laravel Boost:

     composer require laravel/boost
     php artisan boost:install
     

3. First Use Case:

   • Code Review: Trigger an AI agent to review a PR using the code-review.md skill.
   • Bug Fixing: Use bug-fixing.md for guided debugging.
   • Spec-Driven Dev: Apply spec-driven-implementation.md for test-first workflows.
   • Merge Conflicts: Use the resolve-conflicts skill (see Implementation Patterns) to reconcile branches; it invokes dangling-symbols.sh to detect symbols that became orphaned after a merge.

Where to Look First

• Skills Inventory: Browse the Skills section in the README for available skills (e.g., jira-workflows.md, deployment.md, resolve-conflicts/).
• Guidelines: Check the Guidelines section for best practices (e.g., commit messages, PR templates).
• Tag-Gated Extras: Framework-specific skills (e.g., Laravel, Symfony) are tagged and conditionally loaded.
• Shipped Scripts: Skills like resolve-conflicts ship sibling shell scripts (e.g., dangling-symbols.sh). If you rely on them, pin the version and re-run your checks after patch releases — 2.52.1 shipped a fix for declaration/import detection that changes the output of a previously "clean" run.

Implementation Patterns

Core Workflow: Skill Integration

1. Sync Skills to AI Agent:

   • Configure config/boost.php to include sandermuller/boost-skills as a skill source:

     'skills' => [
         'sandermuller/boost-skills',
         // Other skill packages...
     ],
     

   • Run the sync command:

     php artisan boost:sync
     

2. Trigger Skills via CLI:

   • Use Laravel Boost’s boost:run command with a skill name:

     php artisan boost:run code-review --file=path/to/pr.diff
     

   • Example for Jira workflows:

     php artisan boost:run jira-workflows --ticket=PROJ-123
     

3. Merge-Conflict Workflow (resolve-conflicts):

   • Run the skill when a merge or rebase leaves dangling references:

     php artisan boost:run resolve-conflicts
     

   • The skill calls the bundled dangling-symbols.sh to report removed/renamed symbols and their leftovers. As of 2.52.1, it correctly flags:
     • Declarations following a closed block comment on the same line: /** @deprecated */ public function run().
     • Imports following a closed block comment: /* note */ import type Money from './money';.
   • Pipe the script directly in CI to gate merges:

     vendor/sandermuller/boost-skills/skills/resolve-conflicts/dangling-symbols.sh
     

4. Embed Skills in CI/CD:

   • Add a step in .github/workflows/ci.yml to auto-generate PR reviews:

     - name: Run AI Code Review
       run: php artisan boost:run code-review --file=diff.patch
     

Laravel-Specific Patterns

• Tagged Skills: Use laravel-* tagged skills (e.g., laravel-migrations.md) for framework-specific tasks.
• Artisan Command Hooks: Extend existing commands (e.g., php artisan migrate) with AI assistance:

  // app/Console/Commands/MigrateWithAI.php
  public function handle() {
      $this->call('boost:run', ['skill' => 'laravel-migrations']);
      $this->call('migrate');
  }
  

AI Agent Integration

• Cursor/Copilot: Configure the agent to use the synced skills directory (storage/boost/skills).
• Claude Code: Point to the skills/ directory in your Claude workspace settings.

Gotchas and Tips

Pitfalls

1. Not Just Markdown — Version Bumps Matter:

   • While the catalog is markdown-first, some skills (notably resolve-conflicts) ship executable shell helpers. Treat patch releases as potentially behavioral even when the changelog reads like a minor script fix.
   • Fix: Pin to a version ("sandermuller/boost-skills": "2.52.1") and re-run your skill harness after each bump. 2.52.1 changed output behavior for dangling-symbols.sh — a project that previously passed on 2.52.0 may now correctly fail.

2. Sync Engine Required:

   • Most skills are inert without a sync engine (boost-core / laravel/boost) configured to parse and distribute them.
   • Fix: Verify the sync engine is installed and boost:sync completes before invoking skills.

3. Tag Mismatches:

   • Framework-specific skills (e.g., laravel-*) won’t load if the sync engine doesn’t filter by tags.
   • Fix: Check the sync engine’s documentation for tag-based filtering (e.g., --tags=laravel).

4. Skill Overlap:

   • Generic skills (e.g., bug-fixing.md) may conflict with project-specific AI prompts.
   • Fix: Override skills locally by placing custom Markdown files in storage/boost/skills/.

5. AI Agent Limitations:

   • Some agents (e.g., Copilot) may ignore long or complex skills.
   • Fix: Split skills into smaller, focused files (e.g., bug-fixing/debugging.md, bug-fixing/testing.md).

Debugging

• Sync Issues:

  • Run with verbose output:

    php artisan boost:sync --verbose
    

  • Check storage/logs/boost.log for errors.

• Skill Not Loading:

  • Verify the skill exists in vendor/sandermuller/boost-skills/skills/ and isn’t filtered out by tags.

• Script Output Looks Wrong:

  • Run the shell helper directly with bash -x to see how it tokenizes comments and declarations:

    bash -x vendor/sandermuller/boost-skills/skills/resolve-conflicts/dangling-symbols.sh
    

  • If a previously clean sweep suddenly reports dangling symbols, check whether you upgraded past a fix like 2.52.1 that tightened detection around /** ... */ and /* ... */ in-line comments.

Configuration Quirks

1. Custom Skill Paths:

   • Override the default skill path in config/boost.php:

     'skill_paths' => [
         base_path('custom-skills'),
         base_path('vendor/sandermuller/boost-skills/skills'),
     ],
     

2. Dynamic Skill Loading:

   • Use Laravel’s service provider to load skills dynamically:

     // app/Providers/BoostServiceProvider.php
     public function boot() {
         $this->app->when(AiAgent::class)
             ->needs('$skills')
             ->give(fn () => collect(config('boost.skills'))
                 ->map(fn ($skill) => file_get_contents("vendor/{$skill}/skills/*.md"))
                 ->filter()
                 ->values()
             );
     }
     

Extension Points

1. Add Custom Skills:

   • Place new .md files in storage/boost/skills/ or a custom path (see above).
   • Example: storage/boost/skills/project-specific/release-checklist.md.

2. Modify Existing Skills:

   • Override vendor skills by copying them to storage/boost/skills/ and editing locally.
   • If you override resolve-conflicts, also vendor the shell helper and reference it from your copy — otherwise you are pinning behaviour to the vendor script version anyway.

3. Extend Shell-Tooled Skills:

   • Skills that invoke scripts are a good place to hook in project-specific checks (e.g., add a tsc --noEmit pass after dangling-symbols.sh in a resolve-conflicts wrapper).

4. Create Skill Templates:

   • Use the package as a template for your own skill catalog:

     cp -r vendor/sandermuller/boost-skills/skills custom-skills/
     composer require yourname/your-skills
     

5. Integrate with Git Hooks:

   • Auto-trigger skills on pre-commit or pre-push:

     # .git/hooks/pre-commit
     #!/bin/sh
     php artisan boost:run code-review --file=git diff --cached
     

   • For merge safety, add:

     # .git/hooks/pre-push
     #!/bin/sh
     vendor/sandermuller/boost-skills/skills/resolve-conflicts/dangling-symbols.sh