List Skills Command Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install the package:

   composer require stolt/list-skills-command
   

2. Register the command in app/Console/Kernel.php:

   use Stolt\Console\Commands\ListSkillsCommand;
   
   protected $commands = [
       // ... other commands
       ListSkillsCommand::class,
   ];
   

3. Run the command (Laravel's Artisan will now include list-skills):

   php artisan list-skills
   

First Use Case: Discovering Available Skills

• List all skills (default output):

  php artisan list-skills
  

• Get detailed metadata (verbose mode):

  php artisan list-skills --verbose
  

• Filter by tags (e.g., validation):

  php artisan list-skills --tag=validation
  

Implementation Patterns

Workflow Integration

1. Skill Discovery in CI/CD: Use --format-json to generate machine-readable output for CI pipelines:

   php artisan list-skills --format-json > skills.json
   

   Parse skills.json in scripts to dynamically trigger relevant tasks.

2. Documentation Generation: Use --format-md to render skills as a Markdown table for project docs:

   php artisan list-skills --format-md > SKILLS.md
   

3. AI Agent Integration: Leverage auto-detection (via ergebnis/agent-detector) for JSON output when run by AI agents (no manual flag needed).

Laravel-Specific Patterns

• Custom Skill Paths: Override the default skill discovery path by binding a custom path in AppServiceProvider:

  use Stolt\Console\Commands\ListSkillsCommand;
  
  public function register()
  {
      $this->app->bind(ListSkillsCommand::class, function ($app) {
          $command = new ListSkillsCommand();
          $command->setSkillPath(app_path('Skills')); // Custom path
          return $command;
      });
  }
  

• Conditional Command Registration: Dynamically register the command based on environment (e.g., config('app.enable_skills')):

  if (config('app.enable_skills')) {
      $this->commands(ListSkillsCommand::class);
  }
  

• Skill Validation in Tests: Use the command’s built-in validation in PHPUnit:

  public function testSkillsAreValid()
  {
      $this->artisan('list-skills --verbose')
           ->expectsOutput('Check links in llms.txt (1.0.0)')
           ->assertExitCode(0);
  }
  

Gotchas and Tips

Pitfalls

1. Skill File Naming: The command expects skills to follow the SKILL.md convention (e.g., check-links/SKILL.md). Mismatched filenames may cause skills to be ignored. Fix: Ensure filenames match the name in metadata (case-sensitive).

2. Version Parsing: Non-standard version formats (e.g., v1.0.0 vs 1.0.0) may break filtering. Stick to semantic versions (MAJOR.MINOR.PATCH).

3. Path Resolution: Skills must be in a directory scanned by the command. Default paths:

   • ./skills/ (root)
   • ./app/Skills/ (Laravel convention) Tip: Use --verbose to debug missing skills.

4. Tagging Quirks: Tags in SKILL.md must be in the format tags: ["tag1", "tag2"]. Extra spaces or quotes will cause filtering to fail.

Debugging

• Validate Skills Manually: Run with --verbose to see parsed metadata and validation errors:

  php artisan list-skills --verbose
  

  Example output for invalid skills:

  [ERROR] Invalid skill "broken-skill": Missing required field "name".
  

• Check Skill Validator: Understand the stolt/skill-validator rules used for validation (e.g., required name, version, description fields).

Extension Points

1. Custom Metadata Fields: Extend the command by overriding getSkillMetadata() in a subclass:

   class CustomListSkillsCommand extends ListSkillsCommand
   {
       protected function getSkillMetadata(string $path): array
       {
           $metadata = parent::getSkillMetadata($path);
           $metadata['custom_field'] = $this->extractCustomField($path);
           return $metadata;
       }
   }
   

2. Output Formatters: Add new formats by implementing Stolt\Console\Contracts\SkillOutputFormatter and binding it in the service container.

3. Pre/Post-Processing: Use Laravel’s command events to hook into skill listing:

   // In EventServiceProvider
   protected $listen = [
      'artisan.started' => [
          'App\Listeners\LogSkillDiscovery',
      ],
   

];

### Performance Tips
- **Cache Skill Metadata**:
For large projects, cache the parsed metadata in Laravel’s cache:
```php
$cacheKey = 'skills:metadata';
$metadata = Cache::remember($cacheKey, now()->addHours(1), function () {
    return $this->discoverSkills();
});

• Parallel Validation: Use Laravel’s queues to validate skills asynchronously:

  foreach ($skills as $skill) {
      ValidateSkillJob::dispatch($skill);
  }