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, editing any SKILL.md file, editing any file in .ai/ or .claude/skills/ or .github/skills/, updating coding guidelines, modifying AI instructions, or when user mentions: skill, CLAUDE.md, AGENTS.md, guidelines, AI configuration. ALSO activates when about to write or edit a file matching .claude/skills/**/* or .github/skills/**/* — these are generated files that must not be edited directly.

AI Guidelines & Skills Management

Important: Never Edit Generated Files Directly

CLAUDE.md, AGENTS.md, .claude/skills/, and .github/skills/ are auto-generated by Laravel Boost. Any direct edits will be overwritten on the next sync. Always edit the source files in .ai/ instead.

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

CRITICAL: Only edit files in .ai/. The .claude/skills/ and .github/skills/ directories are auto-generated by vendor/bin/testbench package-boost:sync and will be overwritten. If you are about to edit a file in .claude/skills/ or .github/skills/, STOP — find the corresponding file in .ai/skills/ and edit that instead.

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 package-boost:sync after editing any .ai/ files.

vendor/bin/testbench package-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

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

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 package-boost:sync (CRITICAL!)
• Verify git status shows changes in: .ai/, .claude/, .github/, CLAUDE.md, AGENTS.md
• Commit ALL generated files together