Skills Laravel Package

Technical Evaluation

Architecture Fit

• Modularity Alignment: The package leverages Composer’s plugin system, aligning with Laravel’s dependency management ecosystem. It extends Laravel’s existing workflow (e.g., composer install) without disrupting core architecture.
• Skill Isolation: Skills are distributed as self-contained directories (with SKILL.md + auxiliary files), mirroring Laravel’s modular service providers or package structures. This promotes reusability and maintainability.
• Agent-Agnostic Design: The .agents/skills/ directory is tool-agnostic, enabling compatibility with Laravel’s ecosystem (e.g., IDE plugins, CLI tools like Laravel Scout or Forge).

Integration Feasibility

• Low Friction: Requires only a Composer plugin (--dev dependency) and minimal config (skills.json). No Laravel-specific hooks or service providers are needed, reducing integration complexity.
• Laravel-Specific Opportunities:
  • Artisan Integration: Could extend Laravel’s CLI with custom skills:* commands (e.g., php artisan skills:update).
  • Service Provider: Register a SkillServiceProvider to auto-load skills as Laravel services (e.g., for dynamic AI-driven tasks).
  • Package Development: Laravel packages could ship skills natively (e.g., laravel/ai-skill-refactor).
• Dependency Conflicts: Risk of version skew if skills depend on PHP/Laravel versions not aligned with the host project. Mitigate via strict composer.json constraints.

Technical Risk

• Security: Trust model is critical. Malicious skills could inject prompts or execute arbitrary code. Mitigation:
  • Enforce trusted-replace: true in production.
  • Audit donor packages (e.g., via composer skills:show --verbose).
  • Use signed Composer packages (e.g., Composer’s signature verification).
• Performance: Auto-sync on composer install could slow builds. Mitigation:
  • Disable auto-sync ("auto-sync": false) in CI.
  • Use --dry-run to preview changes before syncing.
• Cross-Platform: Junctions/symlinks behave differently on Windows vs. POSIX. Test on target environments.
• Git Conflicts: Aliases (e.g., .claude/skills) may cause merge conflicts if not ignored. Ensure .gitignore coverage.

Key Questions

1. Use Case Clarity:
   • Are skills primarily for developer tooling (e.g., IDE hints, CLI commands) or runtime AI agents (e.g., Laravel Telescope + AI)?
   • Example: Should skills trigger Laravel events (e.g., SkillLoaded) or be consumed via a facade?
2. Laravel-Specific Extensions:
   • Should skills integrate with Laravel’s service container (e.g., resolve skills as bindings)?
   • Could skills be versioned alongside Laravel packages (e.g., laravel/framework ships a debugging skill)?
3. CI/CD Impact:
   • How will skills be tested? Unit tests for SKILL.md content? Integration tests with Laravel’s HTTP layer?
   • Should skills be cached in CI (e.g., via composer skills:update --no-dev)?
4. Governance:
   • Who maintains the trust list? Centralized (e.g., Laravel team) or project-specific?
   • How are skill conflicts resolved (e.g., duplicate SKILL.md files)?
5. Monitoring:
   • Should skill usage be logged (e.g., via Laravel’s logs/skills.log)?
   • Can skills be disabled/enabled dynamically (e.g., via config or environment variables)?

Integration Approach

Stack Fit

• PHP/Laravel: Native Composer integration requires no additional infrastructure. Skills can coexist with Laravel’s:
  • Service Providers: Register skills as dynamic services.
  • Artisan Commands: Extend CLI with php artisan skills:update.
  • Packages: Ship skills alongside Laravel packages (e.g., spatie/laravel-ai).
• AI Tools: Compatible with Laravel-friendly agents like:
  • Claude Code/Cursor: Use aliases (e.g., .claude/skills).
  • Aider: Read from .agents/skills/.
  • Custom Solutions: Laravel’s HTTP layer could expose skills as an API (e.g., /skills/refactor).
• Database: Skills could interact with Laravel’s Eloquent (e.g., Skill::find('refactor') to fetch templates).

Migration Path

1. Pilot Phase:
   • Install in a non-production Laravel project:

     composer require --dev llm/skills
     composer skills:init
     

   • Test with 1–2 skills (e.g., acme/skills-basic).
   • Validate:
     • Skills appear in .agents/skills/.
     • Aliases (e.g., .claude/skills) work.
     • Trust model blocks untrusted packages.
2. Laravel-Specific Customization:
   • Create a Laravel package wrapper (e.g., laravel/skills) to:
     • Add Artisan commands.
     • Register skills as Laravel services.
     • Provide a Skill facade.
   • Example:

     // app/Providers/SkillServiceProvider.php
     public function register()
     {
         $skills = collect(Storage::files('.agents/skills'))->mapWithKeys(function ($path) {
             return [basename(dirname($path)) => new Skill($path)];
         });
         $this->app->instance('skills', $skills);
     }
     

3. Production Rollout:
   • Disable auto-sync in CI ("auto-sync": false).
   • Use composer skills:update in deployment scripts.
   • Audit trusted packages via composer skills:show --verbose.

Compatibility

• Laravel Versions: Test with LTS versions (e.g., 10.x, 11.x) to ensure Composer plugin compatibility.
• PHP Versions: Align with Laravel’s PHP support (e.g., 8.1+).
• Composer: Requires Composer 2.x (plugin system).
• Operating Systems: Test symlink/junction behavior on Windows/Linux/macOS.

Sequencing

1. Pre-requisites:
   • Laravel project with Composer.
   • PHP 8.1+ (for named arguments, attributes).
2. Installation:
   • Add llm/skills to composer.json (dev dependency).
   • Configure skills.json (or use composer skills:init).
3. Skill Acquisition:
   • Install donor packages (e.g., composer require acme/skills-refactor).
   • Sync skills (composer skills:update).
4. Laravel Integration:
   • Register skills in config/app.php or a service provider.
   • Extend with custom commands/facades.
5. CI/CD:
   • Add composer skills:update to deployment pipeline.
   • Cache skills in CI (e.g., composer skills:update --no-dev).

Operational Impact

Maintenance

• Configuration Drift:
  • skills.json must be version-controlled (unlike composer.lock).
  • Use composer skills:init --force to reset config if corrupted.
• Skill Updates:
  • Donor packages update skills via Composer. Monitor for breaking changes in SKILL.md formats.
  • Example: If a skill’s SKILL.md changes its YAML frontmatter, Laravel integrations may need updates.
• Dependency Management:
  • Skills are Composer dependencies. Use composer why-not acme/skills-refactor to debug missing skills.

Support

• Troubleshooting:
  • Skills Not Syncing: Check composer skills:show for skipped packages (trust issues).
  • Permission Errors: Ensure .agents/skills/ is writable (e.g., chmod -R u+rw .agents).
  • Broken Skills: Validate SKILL.md syntax (e.g., valid YAML frontmatter).
• Logging:
  • Enable verbose mode (composer skills:update -v) for debug output.
  • Log skill usage in Laravel (e.g., event(new SkillUsed('refactor'))).
• Documentation:
  • Add a SKILLS.md to the Laravel project root explaining:
    • Trusted packages.
    • How to request new skills.
    • Example SKILL.md templates.

Scaling

• Performance:
  • Large Projects: Auto-sync may slow composer install. Mitigate by:
    • Disabling auto-sync ("auto-sync": false).
    • Running composer skills:update in a separate step.
  • Many Skills: Use --discovery sparingly (scans all vendor packages).
• Storage:
  • Skills are copied to disk. Monitor .agents/skills/ size (e.g., via Laravel’s `