[sylvesterdamgaard]

TLDR: Boost never loaded our guideline. It was at .ai/guidelines/, and Boost only reads that path in the app itself. It now ships at resources/boost/guidelines/core.md, with three task skills next to it, so php artisan boost:install offers all of it.

What changed

• git mv .ai/guidelines/telemetry.blade.php resources/boost/guidelines/core.md. The content is unchanged apart from one line pointing at the skills. It's plain Markdown because it uses no Blade.
• New skills in resources/boost/skills/:
  • telemetry-instrumentation: picking an instrument, OTel names and units, bounded labels, Telemetry::context(), providers, no defensive try/catch.
  • telemetry-debugging-performance: X-Trace-Id, the root-span tallies, N+1 vs duplicate with code.file.path/code.line.number, the X-Telemetry-Label before/after check, telemetry:watch / directives.
  • telemetry-testing: Telemetry::fake(), every assertion, recordedMetrics() label and cardinality budgets, testing providers, RejectingExporter.
• tests/Feature/BoostResourcesTest.php checks four things:
  • every skill parses the way Boost's SkillComposer parses it (name matches the directory, description present, at most 1024 chars);
  • nothing under resources/boost is export-ignored;
  • every Telemetry::x(), $fake->x(), RecordedMetrics assertion and telemetry: command named in the guideline or skills exists;
  • mutation-checked: a bogus method, or an export-ignore on resources/boost, fails it.
• Docs: docs/getting-started/ai-assistants.md (what ships, the direct-dependency catch, the third-party prompt), README, llms.txt, CONTRIBUTING, AGENTS.md (path update), CHANGELOG under [Unreleased].

How Boost finds package skills and guidelines (checked against laravel/boost v2.10.3, latest release, 2026-10-07)

• Skills: resources/boost/skills/{name}/SKILL.md (or SKILL.blade.php). ThirdPartyPackage::skillDirectories() → PackageRegistry::boostPath($package, 'skills') = <package>/resources/boost/skills. SkillComposer::parseSkill() needs YAML frontmatter with name and description and silently skips a skill without them. The docs say the same: Third-Party Package Skills.
• Guidelines: every *.md / *.blade.php under <package>/resources/boost/guidelines/ (GuidelineComposer::getThirdPartyGuidelines()), with the key <package>/<file>. The docs name resources/boost/guidelines/core.blade.php (Third-Party Package AI Guidelines). .md has been accepted since 1.x. .ai/guidelines is base_path('.ai/guidelines') only, which is the app's own directory and is never read from a package.
• Only direct dependencies are read ($package->isDirect()), and boost:install asks which third-party packages to include. The choice is saved in boost.json.
• Skill names share one namespace across all packages (they are keyed by name, and the directory is named after the skill), so ours are prefixed.

Verified end to end

I made a fresh laravel/laravel app, added path repos for this branch and the matching UI and insights branches, and installed laravel/boost 2.10.3. Then I ran php artisan boost:install --guidelines --skills -n:

• CLAUDE.md now contains === cboxdk/laravel-telemetry/core rules ===.
• .claude/skills/ now contains telemetry-instrumentation, telemetry-debugging-performance, telemetry-testing, telemetry-ui-mcp and telemetry-insights-triage.
• git archive HEAD includes resources/boost/**.

composer check is green.

Sibling PRs: cboxdk/laravel-telemetry-ui#17 (telemetry-ui-mcp) and cboxdk/laravel-telemetry-insights#4 (telemetry-insights-triage).

https://claude.ai/code/session_01LtsaMBeethcCYvKx8PTBYL