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 sandermuller/boost-core (Composer plugin). Any direct edits will be overwritten on the next composer install/update (the plugin syncs on POST_AUTOLOAD_DUMP when boost.php exists at the project root) or when you run vendor/bin/boost sync manually.

Laravel projects with sandermuller/project-boost-laravel installed: substitute php artisan project-boost:sync for vendor/bin/boost sync everywhere in this skill. The Laravel wrapper bootstraps the application container before invoking boost-core's SyncEngine; the bare vendor/bin/boost sync currently errors on Container::path() in Laravel projects.

Project Structure

.ai/                              # SOURCE - Edit files here
├── guidelines/                   # Project-wide AI instructions
│   └── *.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/, .github/skills/, .cursor/skills/, etc. directories are auto-generated by vendor/bin/boost sync (boost-core's Composer plugin) and will be overwritten. They are also auto-gitignored via boost-core's managed .gitignore block (sentinels # >>> boost (managed) >>> … # <<< boost (managed) <<<), so they never get committed.

How sandermuller/boost-core Works (in Package Context)

This package uses sandermuller/boost-core (Composer plugin, framework-agnostic):

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 combines these with installed vendor packages' boost skills/guidelines to generate CLAUDE.md, AGENTS.md, GEMINI.md, and per-agent <.agent>/skills/ directories
4. Plugin auto-syncs on composer install/update (POST_AUTOLOAD_DUMP) when boost.php exists at project root. Otherwise run vendor/bin/boost sync manually.

Updating Guidelines

Guideline files in .ai/guidelines/ are standard Markdown (.md). Keep them concise and scoped to conventions that persist across the project.

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

Documenting External Tools in Skills

When a skill interacts with external services (issue trackers, CI, CLIs, MCP servers), document the exact tool invocation the skill should use. Prefer slim, machine-readable responses over full payloads — e.g. for GitHub, document the exact gh command including the --json <fields> field list and/or --jq filter rather than fetching the entire payload.

Regenerating Generated Files

The boost-core Composer plugin auto-syncs .ai/ → generated files on composer install/update when boost.php exists at the project root. To force a sync manually (or for repos without boost.php):

vendor/bin/boost sync

This syncs .ai/ changes to per-agent locations:

Generated File/Directory	Purpose
CLAUDE.md	Main context file for Claude Code
AGENTS.md	Shared context for Codex / Copilot / Cursor / Amp / Junie / Kiro / OpenCode / etc.
GEMINI.md	Main context file for Gemini
.claude/skills/	Skills loaded by Claude Code
.cursor/skills/	Skills loaded by Cursor
.github/skills/	Skills for GitHub Copilot (Copilot reads root AGENTS.md for guideline context per the GitHub 2025-08 changelog)
.amp/skills/, .gemini/skills/, .junie/skills/, .kiro/skills/, .opencode/skills/, .agents/skills/	Per-agent skill dirs

Generated files are auto-gitignored via boost-core's managed .gitignore block — they never get committed. Only the .ai/ sources are tracked.

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 (or rely on auto-sync if boost.php exists)
• Verify git status shows changes in .ai/ only — generated files are gitignored
• Commit .ai/ sources; generated files propagate on consumers' next composer install/update