Getting Started

Minimal Steps

There are now two ways to get skills into a project: the Composer plugin (unchanged) or the standalone binary shipped as of 1.15.0.

Option A — Composer plugin (existing projects):

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.

Option B — Standalone binary (new in 1.15.0):

Download the binary for your platform (Linux, macOS, Windows) from the 1.15.0 release assets.

Make it executable and put it on your PATH:

chmod +x skills
mv skills /usr/local/bin/skills

Run the same commands without the Composer prefix:
```
skills init
skills update
skills show
```
Point it at your project (run from the project root, same as the plugin — it reads skills.json and composer.json/composer.lock).

Use Option A when you want skills synced automatically on every composer install/update. Use Option B when you have no PHP toolchain available (docs sites, Node/Go services, Docker images without PHP) or when you want to generate skills in CI before PHP is installed.

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 (or skills update if using the binary).
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
# or, with the binary:
skills update --discovery

Temporarily trust a package for testing:

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

4. Binary-First Workflow (new in 1.15.0)

Skip installing the Composer plugin and keep composer.json untouched apart from the donor packages you require.

Install the binary once per machine or per container image, pinned to a version:

ARG SKILLS_VERSION=1.15.0
RUN curl -fsSL -o /usr/local/bin/skills \
      "https://github.com/roxblnfk/skills/releases/download/${SKILLS_VERSION}/skills-linux-amd64" \
    && chmod +x /usr/local/bin/skills

Then sync explicitly in a script or CI step:
```
skills update
```
Because the binary is self-contained, it is also the sane choice for polyglot monorepos where only some subprojects have PHP — one tool, one version, all projects.

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 (plugin path): Ensure skills.json has "auto-sync": true to sync skills during composer install in CI.
```
- run: composer install
# Skills auto-synced here
- run: php artisan test
```

Sync Before the PHP Toolchain Exists (binary path, 1.15.0): Useful when your AI/lint job runs on a slimmer image than your PHP job:

- name: Sync skills
  run: |
    curl -fsSL -o /usr/local/bin/skills \
      https://github.com/roxblnfk/skills/releases/download/1.15.0/skills-linux-amd64
    chmod +x /usr/local/bin/skills
    skills update

Cache Skills in CI: Add .agents/skills/ to your CI 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') }}

Pin the binary version in CI (1.15.0, not latest) — same reason you commit composer.lock. A drifting skills binary changes what your AI agents read between builds.

Debugging and Dry Runs

Preview changes before syncing:
```
skills update --dry-run
```
Inspect sync status:
```
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:
```
skills update vendor/package --trust="vendor/*"
```
- Debug: Run 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:
```
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 skills update.
Malformed skills.json:
- Issue: Invalid JSON or unknown keys cause fatal errors.
- Fix: Use 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.
Mixing Plugin and Binary (new in 1.15.0):
- Issue: If the Composer plugin is installed and you also run the binary, you can end up with two different tool versions writing to the same .agents/skills/. Auto-sync from the plugin may silently overwrite (or lag behind) what the binary produced, producing confusing "it worked yesterday" behaviour.
- Fix: Pick one driver per repository. If you keep the plugin, don't call the binary in scripts; if you go binary-only, remove llm/skills from require-dev and drop the allow-plugins entry.
Binary Not on PATH in Non-Interactive Shells:
- Issue: CI runners, cron jobs and Docker RUN steps frequently use a shell that does not source your profile, so skills is "command not found" even though it works in your terminal.
- Fix: Install to an absolute location (/usr/local/bin) or invoke by full path in scripts.
Windows Binary Invocation:
- Issue: In PowerShell, a binary in the current directory needs an explicit .\ prefix (.\skills.exe update), and SmartScreen may block an unsigned downloaded executable.
- Fix: Install to a directory on %PATH%, invoke with .\ when testing locally, and unblock with Unblock-File if SmartScreen quarantines the download.

Debugging Tips

Verbose Output: Use -v or -vv for detailed logs:
```
skills update -vv
```
Check Sync Status:
```
skills show
```
Look for SKIPPED entries to identify trust or discovery issues.
Validate Donor Packages: Ensure donor packages declare extra.skills correctly. Test with:
```
skills update --discovery
```
Confirm Which Build You Are Running: When a sync behaves differently on a colleague's machine or in CI, check the version of whichever driver produced the output — composer skills:show for the plugin path, skills --version for the binary — before chasing config problems.
Manual Sync: For debugging, manually trigger sync:
```
skills update
```

Extension Points

Custom Trust Logic: Override trust behavior by extending the plugin or using --trust dynamically:
```
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"
    ]
  }
}
```
This hook only fires on the Composer path — with the binary, wire the follow-up explicitly in your Makefile, Taskfile or CI step.
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:
```
skills update --discovery
```
Wrapper Script for Teams: Wrap the binary in a small bin/skills script that pins the version and passes house defaults, so every developer and CI job gets identical behaviour without memorising flags:
```
#!/usr/bin/env bash
exec skills update --discovery --trust="vendor/*" "$@"
```

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);
    }
}
```
This works identically whether the skills directory was populated by the plugin or the standalone binary — the output on disk is the same format.
Skill-Based Artisan Commands: Create a custom Artisan command to generate files from skills, so developers who never touch the CLI tooling still get the templates:
```
// app/Console/Commands/
```

Skills Laravel Package