| 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):
- Guidelines in
.ai/guidelines/ define project-wide coding conventions
- Skills in
.ai/skills/ provide domain-specific instructions activated on demand
- 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
- 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
