ai-guidelines

Category: Development & Coding | Uploader: SanderMuller | Downloads: 0 | Version: v1.0（Latest）

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.

Changelog: Source: GitHub https://github.com/SanderMuller/Stopwatch

Directory Structure

Current level: tree/main/.ai/skills/ai-guidelines/

📄 SKILL.md 3.7 KB

SKILL.md

---
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:

```markdown
---
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.**

```bash
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**

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

ai-guidelines

Directory Structure

SKILL.md

Report

Notice