ai-guidelines

name	ai-guidelines
description	MUST USE when creating, updating, or managing AI skills and guidelines. Activates when: creating a new skill, editing existing skills, updating coding guidelines, modifying AI instructions, working with .ai/ directory, or when user mentions: skill, CLAUDE.md, guidelines, AI configuration.

AI Guidelines & Skills Management

Important: Never Edit CLAUDE.md or AGENTS.md Directly

These files are auto-generated by Laravel Boost. Any direct edits will be overwritten.

Project Structure

.ai/                              # SOURCE - Edit files here
├── guidelines/                   # Project-wide AI instructions
│   └── *.blade.php / *.md        # Coding conventions
└── skills/                       # Skill definitions
    └── {skill-name}/SKILL.md     # One folder per skill

.claude/skills/                   # AUTO-GENERATED - Do not edit
└── {skill-name}/SKILL.md         # Skills for Claude Code

.github/skills/                   # AUTO-GENERATED - Do not edit
└── {skill-name}/SKILL.md         # Skills for GitHub Copilot

Important: Only edit files in .ai/. The .claude/skills/ and .github/skills/ directories are auto-generated by vendor/bin/boost sync (boost-core) and will be overwritten.

How boost-core Works (in Package Context)

This package uses sandermuller/boost-core (a Composer plugin):

1. Guidelines in .ai/guidelines/ define project-wide coding conventions
2. Skills in .ai/skills/ provide domain-specific instructions activated on demand
3. boost-core fans these out to every agent dir on composer install/update via its POST_AUTOLOAD_DUMP subscriber (or on demand via vendor/bin/boost sync)

Updating Guidelines

Edit files in .ai/guidelines/:

• Blade files (.blade.php): Use @verbatim blocks around code examples
• Markdown files (.md): Standard markdown format

Creating/Updating Skills

Skills live in .ai/skills/{skill-name}/SKILL.md with frontmatter:

---
name: skill-name
description: When this skill activates. Include trigger words and scenarios.
---

# Skill Title

## When to use this skill

- Scenario 1
- Scenario 2

## Instructions

Detailed instructions for the skill...

Skill Naming

• Use kebab-case for directory names: my-new-skill/
• The name in frontmatter should match the directory name
• Write clear description with activation triggers

Regenerating Generated Files

composer install / composer update auto-fires boost sync via the plugin's POST_AUTOLOAD_DUMP subscriber. Run it manually when needed:

vendor/bin/boost sync

This syncs your .ai/ changes to all generated locations:

Generated File/Directory	Purpose
CLAUDE.md	Main context file for Claude
AGENTS.md	Main context file for Codex
.claude/skills/	Skills loaded by Claude Code
.github/skills/	Skills for GitHub Copilot
.github/copilot-instructions.md	Instructions for GitHub Copilot

These files are gitignored — boost-core regenerates them on every install. Commit only .ai/ sources.

Checklist for Changes

• Edit files in .ai/guidelines/ or .ai/skills/ (never edit generated files)
• Include clear activation triggers in skill descriptions
• Run vendor/bin/boost sync if you want to preview the generated output locally
• Commit only .ai/ source changes — generated files are gitignored