Getting Started

Minimal Steps

Install the package in your Laravel project:
```
composer require --dev llm/skills
```

Enable the plugin in composer.json:

{
  "config": {
    "allow-plugins": {
      "llm/skills": true
    }
  }
}

Initialize the config (optional but recommended):
```
composer skills:init
```
This creates a skills.json file in your project root with default settings.

Add a skill package to your composer.json:

{
  "require-dev": {
    "vendor/skill-package": "^1.0"
  }
}

Run composer update to install it. The package should declare its skills in extra.skills:

{
  "extra": {
    "skills": {
      "source": "path/to/skills"
    }
  }
}

Verify skills are synced:
```
composer skills:show
```
Check the .agents/skills/ directory for the imported skills.

First Use Case

Integrate a skill for AI-assisted Laravel migrations:

Install a migration skill package:

composer require --dev vendor/laravel-migration-skills

Configure skills.json to trust the package:
```
{
  "trusted": ["vendor/*"]
}
```
Run composer update to auto-sync the skill.
Use the skill in your AI tool (e.g., Claude Code) by pointing it to .agents/skills/migrate/.

Implementation Patterns

Workflows

1. Skill Development Workflow

Vendor Side:
- Structure skills in a resources/skills/ directory (e.g., resources/skills/laravel-auth/).
- Define SKILL.md with Laravel-specific instructions (e.g., authentication flow templates).
- Declare the skill in composer.json:
```
{
  "extra": {
    "skills": {
      "source": "resources/skills"
    }
  }
}
```
- Publish the package to Packagist.
Consumer Side:
- Add the package to composer.json under require-dev.
- Run composer update to auto-sync skills to .agents/skills/.
- Use the skill in your AI tool (e.g., SKILL.md for generating Laravel auth controllers).

2. Multi-Agent Setup

Configure skills.json to create aliases for different agents:

{
  "target": ".agents/skills",
  "aliases": [".claude/skills", ".cursor/skills"]
}

Point each AI tool to its respective alias (e.g., Claude Code to .claude/skills).

3. Dynamic Skill Loading

Use --discovery to include packages without explicit extra.skills:
```
composer skills:update --discovery
```

Temporarily trust a package for testing:

composer skills:update vendor/package --trust="vendor/*"

Integration Tips

Laravel-Specific Integrations

Skill for Artisan Commands:
- Create a skill with SKILL.md containing Artisan command templates.
- Example:
```
# SKILL.md
## Laravel Command Generation
Use this skill to generate Artisan commands for:
- Database seeding
- Queue workers
- Console commands
```
- Include a templates/command.stub file for AI to fill in.
Skill for Migration Writes:
- Structure a skill with SKILL.md for migration logic and templates/migration.stub.
- Example SKILL.md:
```
## Laravel Migration Helper
Generate migrations for:
- Table creation with indexes
- Foreign key constraints
- Soft deletes
```
- Use the skill in your AI tool to auto-generate migration files.
Skill for API Resource Handling:
- Define a skill with SKILL.md for API resource boilerplate (e.g., App\Http\Resources\PostResource).
- Include templates for:
  - Resource classes
  - API routes
  - Request validation rules.

CI/CD Integration

Auto-Sync in CI: Ensure skills.json has "auto-sync": true to sync skills during composer install in CI. Example GitHub Actions step:
```
- run: composer install
# Skills auto-synced here
- run: php artisan test
```

Cache Skills in CI: Add .agents/skills/ to your CI cache (e.g., GitHub Actions cache) to avoid re-downloading skills on every run:

- uses: actions/cache@v3
  with:
    path: |
      vendor
      .agents/skills
    key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}

Debugging and Dry Runs

Preview changes before syncing:
```
composer skills:update --dry-run
```
Inspect sync status:
```
composer skills:show
```

Gotchas and Tips

Pitfalls

Trust Misconfiguration:
- Issue: Forgetting to trust a package or namespace causes skills to be skipped.
- Fix: Explicitly add the package to skills.json under "trusted" or use --trust in CLI:
```
composer skills:update vendor/package --trust="vendor/*"
```
- Debug: Run composer skills:show to see skipped packages and reasons.
Alias Conflicts:
- Issue: Alias paths (e.g., .claude/skills) already exist as directories, causing failures.
- Fix: Remove the conflicting directory manually or use --alias to override:
```
composer skills:update --alias=.claude/skills
```
- Note: The plugin never deletes existing directories to avoid data loss.
Auto-Sync Overrides:
- Issue: composer install --no-scripts disables auto-sync, leaving skills unsynced.
- Fix: Ensure skills.json has "auto-sync": true or manually run:
```
composer skills:update
```
Malformed skills.json:
- Issue: Invalid JSON or unknown keys cause fatal errors.
- Fix: Use composer skills:init to generate a valid template or validate against the schema:
```
{
  "$schema": "https://raw.githubusercontent.com/roxblnfk/skills/master/resources/skills.schema.json"
}
```
Cross-Platform Alias Issues:
- Issue: Windows junctions fail for cross-volume paths.
- Fix: Ensure all alias paths are on the same drive or avoid cross-volume junctions.

Debugging Tips

Verbose Output: Use -v or -vv flags for detailed logs:
```
composer skills:update -vv
```
Check Sync Status:
```
composer skills:show
```
- Look for SKIPPED entries to identify trust or discovery issues.
Validate Donor Packages: Ensure donor packages declare extra.skills correctly. Test with:
```
composer skills:update --discovery
```
Manual Sync: For debugging, manually trigger sync:
```
composer skills:update
```

Extension Points

Custom Trust Logic: Override trust behavior by extending the plugin or using --trust dynamically:
```
composer skills:update --trust="vendor/*" --trust="another/*"
```

Post-Sync Hooks: Add a post-update-cmd script in composer.json to run custom logic after sync:

{
  "scripts": {
    "post-update-cmd": [
      "@php artisan skills:update",
      "@php artisan your:custom-task"
    ]
  }
}

Custom Target Directory: Override the default .agents/skills path in skills.json:
```
{
  "target": "custom/skills/path"
}
```
Dynamic Skill Loading: Use --discovery to include packages without explicit skill declarations:
```
composer skills:update --discovery
```

Laravel-Specific Quirks

Service Provider Integration: Load skills dynamically in a service provider:

public function boot()
{
    $skillsPath = base_path('.agents/skills');
    if (file_exists($skillsPath)) {
        $this->loadSkillsFrom($skillsPath);
    }
}

Skill-Based Artisan Commands: Create a custom Artisan command to generate files from skills:
```
// app/Console/Commands/
```

Skills Laravel Package