AI Guidelines and Skills

This page describes the AI Guidelines and Agent Skills that this package configures for PhpStorm with GitHub Copilot. These components provide project-specific instructions, conventions, and domain knowledge to guide AI-assisted development within Laravel projects.

For information about how these guidelines are registered with the Laravel Boost framework, see Laravel Boost Integration. For details on how they are delivered to PhpStorm Copilot through the MCP protocol, see MCP Server Architecture.

---

Purpose and Installation

The package installs two types of AI configuration files when you run boost:install and select the appropriate features:

Feature Selection	Files Installed	Purpose
AI Guidelines	.github/instructions/laravel-boost.instructions.md	Project-wide coding standards, conventions, and best practices
Agent Skills	.github/skills/*/SKILL.md	Domain-specific knowledge modules that activate contextually

These files are created by the PhpStormCopilot agent class when it implements the SupportsGuidelines and SupportsSkills contracts from Laravel Boost.

Sources: src/PhpStormCopilot.php86-97

---

File Structure and Locations

Published File System Structure:

Published File Locations:

File Type	Destination Path	Template Source
Guidelines	.github/instructions/laravel-boost.instructions.md	resources/boost/guidelines/core.blade.php (one contributing section)
Pest Skill	.github/skills/pest-testing/SKILL.md	resources/boost/skills/pest-testing/SKILL.md (in package resources)

The guidelinesPath() and skillsPath() methods on PhpStormCopilot return these destination paths. The laravel/boost framework uses them to know where to write published files within the developer's project.

Sources: src/PhpStormCopilot.php86-97 .github/instructions/laravel-boost.instructions.md1 .github/skills/pest-testing/SKILL.md1 resources/boost/guidelines/core.blade.php1

---

AI Guidelines Structure

The guidelines file .github/instructions/laravel-boost.instructions.md1-248 contains multiple rule sections organized by topic, wrapped in a <laravel-boost-guidelines> XML container. Each section provides specific coding standards and tool usage instructions.

XML Container Structure:

Guidelines Content Sections

Rule Section Organization:

Sources: .github/instructions/laravel-boost.instructions.md1-248

Key Guidelines Sections

Section	Lines	Purpose
Foundation Rules	2-51	Application context (PHP 8.5.2, Laravel 12, Pest 4), skill activation instructions, conventions
Boost Rules	53-92	Laravel Boost MCP tool usage, list-artisan-commands, get-absolute-url, tinker, search-docs
PHP Rules	92-127	Constructor property promotion, type declarations, enum conventions, PHPDoc standards
Laravel Core Rules	128-182	Eloquent relationships, Form Requests, authentication, URL generation, queues, testing with factories
Laravel 12 Rules	183-207	Bootstrap/app.php structure, middleware configuration, database features, casts() method
Pint Rules	208-214	Code formatting with vendor/bin/pint --dirty
Pest Rules	215-224	Test creation, execution, documentation search, skill activation

Sources: .github/instructions/laravel-boost.instructions.md1-248

Foundational Context Example

The guidelines specify exact package versions to ensure AI provides version-appropriate code:

## Foundational Context

This application is a Laravel application and its main Laravel ecosystems package & versions are below.

- php - 8.5.2
- laravel/framework (LARAVEL) - v12
- laravel/mcp (MCP) - v0
- laravel/prompts (PROMPTS) - v0
- laravel/pint (PINT) - v1
- pestphp/pest (PEST) - v4
- phpunit/phpunit (PHPUNIT) - v12

Sources: .github/instructions/laravel-boost.instructions.md8-18

Skills Activation Instructions

The guidelines .github/instructions/laravel-boost.instructions.md20-24 include explicit instructions for when to activate domain-specific skills. This ensures AI assistance activates the appropriate skill context based on developer actions or keywords.

Skill Activation Pattern:

Component	Content
Trigger Keywords	test, spec, TDD, expects, assertion, coverage
Action Triggers	Writing tests, creating unit/feature tests, adding assertions, debugging test failures
Domain Triggers	Testing Livewire components, browser testing, working with datasets or mocking
Skill Name	pest-testing
Activation Timing	"MUST activate...whenever you work in that domain—don't wait until you're stuck"

Example Activation Text:

Sources: .github/instructions/laravel-boost.instructions.md20-24

---

Agent Skills

Skills are domain-specific knowledge modules stored as individual directories under .github/skills/. Each skill contains a SKILL.md file with YAML frontmatter and detailed documentation.

Skill File Format

Sources: .github/skills/pest-testing/SKILL.md1-174

pest-testing Skill Structure

The included pest-testing skill demonstrates the skill format:

Component	Content
Frontmatter	name: pest-testing, description with activation triggers
When to Apply	Creating tests, modifying tests, debugging failures, browser/architecture testing
Documentation	Reference to search-docs tool for Pest 4 patterns
Basic Usage	Test creation commands, test organization, basic structure, running tests
Assertions	Specific assertion methods table (assertSuccessful() vs assertStatus(200))
Mocking	Import instructions for use function Pest\Laravel\mock;
Datasets	Examples of dataset usage for repetitive tests
Pest 4 Features	Browser testing, smoke testing, visual regression, test sharding, architecture testing
Common Pitfalls	List of frequent mistakes to avoid

Sources: .github/skills/pest-testing/SKILL.md1-174

Skill Activation Triggers

Sources: .github/skills/pest-testing/SKILL.md1-21 .github/instructions/laravel-boost.instructions.md20-24

---

Code Snippet Format in Skills

Skills use a custom <code-snippet> XML format to provide example code:

Examples from pest-testing Skill

Snippet Name	Lines	Purpose
Basic Pest Test Example	40-45	Demonstrates it() syntax with expect() assertions
Pest Response Assertion	58-64	Shows assertSuccessful() instead of assertStatus(200)
Pest Dataset Example	80-90	Demonstrates dataset usage with with() method
Pest Browser Test Example	114-133	Full browser test with visit(), interactions, assertions
Pest Smoke Testing Example	139-145	Quick multi-page validation
Architecture Test Example	159-165	Enforcing code conventions with arch()

Sources: .github/skills/pest-testing/SKILL.md40-167

---

AI Interaction Flow with Guidelines and Skills

Runtime Interaction Sequence:

Sources: .github/instructions/laravel-boost.instructions.md20-24 .github/skills/pest-testing/SKILL.md1-174 resources/boost/guidelines/core.blade.php1-33

---

Guidelines Best Practices

The guidelines enforce specific Laravel development patterns:

Eloquent and Database Patterns

• Always use proper Eloquent relationship methods with return type hints
• Prefer Model::query() over DB::
• Use eager loading to prevent N+1 queries
• Generate factories and seeders when creating models
• Use Eloquent API Resources for APIs

Sources: .github/instructions/laravel-boost.instructions.md138-151

Form Validation Pattern

• Always create Form Request classes for validation
• Never use inline validation in controllers
• Include both validation rules and custom error messages
• Check sibling Form Requests for array vs string rule conventions

Sources: .github/instructions/laravel-boost.instructions.md153-156

Laravel Boost MCP Tool Usage

Tool	When to Use
list-artisan-commands	Before calling Artisan commands to check available parameters
get-absolute-url	When sharing project URLs with correct scheme, domain/IP, port
tinker	Execute PHP to debug code or query Eloquent models
database-query	Read from database without full Eloquent context
browser-logs	Read recent browser logs, errors, exceptions
search-docs	Before making code changes - searches version-specific docs for installed packages

Sources: .github/instructions/laravel-boost.instructions.md59-91

Documentation Search Strategy

The guidelines provide specific instructions for using the search-docs tool:

- Use multiple, broad, simple, topic-based queries at once. 
 For example: ['rate limiting', 'routing rate limiting', 'routing']. 
 The most relevant results will be returned first.
- Do not add package names to queries; package information is already shared. 
 For example, use 'test resource table', not 'filament 4 test resource table'.

Available Search Syntax:

1. Simple Word Searches with auto-stemming - authentication finds 'authenticate' and 'auth'
2. Multiple Words (AND Logic) - rate limit finds both "rate" AND "limit"
3. Quoted Phrases (Exact Position) - "infinite scroll" words must be adjacent
4. Mixed Queries - middleware "rate limit" combines word and phrase
5. Multiple Queries - ["authentication", "middleware"] finds ANY term

Sources: .github/instructions/laravel-boost.instructions.md78-91

---

Laravel 12 Specific Guidelines

The guidelines include version-specific instructions for Laravel 12's streamlined structure:

Topic	Guideline
Middleware Registration	No longer in app/Http/Kernel.php, use bootstrap/app.php with Application::configure()->withMiddleware()
Bootstrap Configuration	bootstrap/app.php for middleware, exceptions, routing; bootstrap/providers.php for service providers
Console Kernel	app\Console\Kernel.php no longer exists, use bootstrap/app.php or routes/console.php
Console Commands	Auto-discovered from app/Console/Commands/, no manual registration needed
Model Casts	Can use casts() method instead of $casts property, follow existing conventions
Eager Loading Limits	Native support: $query->latest()->limit(10) without external packages

Sources: .github/instructions/laravel-boost.instructions.md183-207

---

Implementation in PhpStormCopilot Agent

The PhpStormCopilot class in src/PhpStormCopilot.php implements Laravel Boost contracts that enable guidelines and skills functionality.

Contract Implementation Architecture:

Contract Method Implementations:

Contract	Method	Return Type	Default Return Value	Config Key
SupportsGuidelines	guidelinesPath()	string	.github/instructions/laravel-boost.instructions.md	boost.agents.phpstorm_copilot.guidelines_path
SupportsSkills	skillsPath()	string	.github/skills	boost.agents.phpstorm_copilot.skills_path

Both return values can be overridden via the application's boost config. The returned string is the destination path inside the developer's project where the file will be written.

Publishing Process:

1. php artisan boost:install invokes the Laravel Boost installation flow
2. Boost framework calls guidelinesPath() and skillsPath() on the registered PhpStormCopilot agent
3. Template files from resources/boost/guidelines/ and resources/boost/skills/ are rendered and written to the destination paths
4. Published files become available to artisan boost:mcp at runtime

Sources: src/PhpStormCopilot.php86-97 resources/boost/guidelines/core.blade.php1-33

---

Package-Specific Guidelines

The guidelines .github/instructions/laravel-boost.instructions.md225-248 include a section specific to this package's development environment, which uses Orchestra Testbench instead of a full Laravel application.

Package Development Environment Rules:

Topic	Guideline	Reason
MCP Config Flag	copilot --additional-mcp-config @.github/mcp-config.json --continue	Required for every Copilot CLI session to access Laravel Boost MCP tools
Environment Type	Laravel package development project using Orchestra Testbench	Not a standard Laravel application
Available Commands	vendor/bin/testbench instead of php artisan	Orchestra Testbench provides isolated package testing environment
MCP Tool Availability	Tools like database-query, database-schema, list-routes may return limited results	Package environment lacks full application context, database, application-specific models
Working Tools	application-info, list-artisan-commands, search-docs	Basic tools that don't depend on application-specific features
Development Focus	Writing tests, implementing package features, ensuring Laravel compatibility	Package-specific development tasks

MCP Configuration File Location:

.github/mcp-config.json

This file is referenced using the --additional-mcp-config flag when starting Copilot CLI from the package's root directory.

Sources: .github/instructions/laravel-boost.instructions.md225-248

---

Guidelines vs Skills Comparison

Aspect	AI Guidelines	Agent Skills
File Location	.github/instructions/laravel-boost.instructions.md	.github/skills/*/SKILL.md
Scope	Project-wide, always active	Domain-specific, contextually activated
Format	Sectioned markdown with XML wrapper	YAML frontmatter + markdown content
Purpose	Coding standards, conventions, tool usage	Deep domain knowledge for specific tasks
Contract	SupportsGuidelines	SupportsSkills
Activation	Automatic on every AI interaction	Triggered by context or keywords
Content Type	Rules, preferences, version info	Patterns, examples, pitfalls, detailed how-to
Examples	"Use Form Requests for validation"	Complete test structure with code snippets

Sources: .github/instructions/laravel-boost.instructions.md1-248 .github/skills/pest-testing/SKILL.md1-174