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/testbench boost:update and will be overwritten.

How Laravel Boost Works (in Package Context)

This package uses Laravel Boost via Orchestra Testbench:

1. Guidelines in .ai/guidelines/ define project-wide coding conventions
2. Skills in .ai/skills/ provide domain-specific instructions activated on demand
3. Laravel Boost combines these with its built-in rules to generate CLAUDE.md and AGENTS.md
4. Run via vendor/bin/testbench instead of php artisan

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

CRITICAL: Always run boost:update before committing any changes to .ai/ files.

vendor/bin/testbench boost:update

This command 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

All these files must be committed together — they are kept in sync by boost:update.

Checklist for Changes

• Edit files in .ai/guidelines/ or .ai/skills/ (never edit generated files)
• Use @verbatim blocks in Blade files for code examples
• Include clear activation triggers in skill descriptions
• Run vendor/bin/testbench boost:update (CRITICAL!)
• Verify git status shows changes in: .ai/, .claude/, .github/, CLAUDE.md, AGENTS.md
• Commit ALL generated files together