| name | skill-authoring |
| description | MUST USE when authoring an AI skill — creating a new SKILL.md, naming a skill, or deciding where one lives. Covers namespacing across host/vendor/shipped skills, auto-activating frontmatter, `.ai/skills/` vs `resources/boost/skills/` choice, and `boost sync` regen. Activates: creating a skill, adding a skill, drafting a SKILL.md, naming a skill, choosing where a skill lives, editing `.ai/skills/**/SKILL.md` or `resources/boost/skills/**/SKILL.md`; mentions: skill, SKILL.md, skill name, skill namespace, skill collision, vendor skill, shipped skill. |
Skill Authoring
Guidance for adding a new AI skill to a package that uses
package-boost. Covers the four things models routinely get wrong:
name collisions, dead descriptions, wrong source
directory, and forgotten sync.
This skill is about SKILL.md authoring only. For
.ai/guidelines/*.md content, see the package-development skill's
Authoring guidelines section.
When to use this skill
- Creating a new skill in a package (host repo or vendor package).
- Renaming an existing skill.
- Reviewing a skill's frontmatter or location before merging.
1. Namespace the skill name
Skills merge in load order, and later entries silently override
earlier ones on name collisions:
- Package-boost's shipped defaults
- Vendor packages, alphabetical by
vendor/name
- Host
.ai/
That ordering produces three real collision modes:
| Mode | Example | Effect |
|---|
| Host masks vendor | Host adds .ai/skills/billing-audit/, vendor acme/billing ships resources/boost/skills/billing-audit/ | Vendor's skill never loads. No warning. |
| Vendor masks vendor | acme/billing and widgets/co both ship resources/boost/skills/migrate/ | Vendors load alphabetically and later entries overwrite earlier ones, so widgets/co wins; acme/billing's loses. No warning. |
| Vendor masks package-boost default | Vendor ships resources/boost/skills/readme/ | Vendor overrides package-boost's shipped readme skill in every consumer. Easy to do by accident. |
Avoid all three by prefixing:
{vendor}-{topic} — e.g. acme-billing-audit, widgets-migrate.{package}-{topic} — e.g. nova-fields-validate,
livewire-volt-recipes.
Required for vendor-shipped skills. Recommended for host skills
that overlap with anything common.
Reserved shipped-skill names
Package-boost itself ships these; do not name a vendor or host skill
the same unless you intend to override:
ci-matrix-troubleshootingcross-version-laravel-supportlean-distpackage-developmentreadmerelease-notesskill-authoringupgrading
Run ls vendor/sandermuller/package-boost/resources/boost/skills/
in your project to see the current list.
2. Pick the right source directory
| Audience | Path | Notes |
|---|
| Skill for your own repo | .ai/skills/{name}/SKILL.md | Stays local; not shipped to your package's consumers. |
| Skill shipped to your package's consumers | resources/boost/skills/{name}/SKILL.md | Picked up by package-boost in every consumer that installs your package. Namespacing mandatory. |
Generated outputs in per-agent directories (.claude/skills/,
.cursor/skills/, .agents/skills/, .github/skills/,
.junie/skills/, .kiro/skills/) are written by
boost sync. Never edit those directly — your edits get
overwritten on the next sync.
Directory name must be kebab-case and match the name field in
frontmatter exactly.
3. Write a description that actually triggers
The frontmatter description is the trigger surface for
auto-activation and counts against a global skill-description
budget — every word ships in every host's prompt. A vague description
("Helps with reviews") never matches; a bloated one wastes tokens.
Aim for specific and terse, in that order.
Triggers come first. When trimming an existing description, never
remove or compress a user-facing trigger phrase to save tokens.
Trim the surrounding prose instead. Concretely:
- Keep every trigger phrase verbatim — do not abbreviate
(
backwards compatibility not backwards compat,
minimum laravel version not min laravel version).
- Do not collapse distinct phrases into slash-shorthand
(
.claude in tarball, CLAUDE.md in tarball — not
.claude/CLAUDE.md in tarball). Users type one or the other,
not the bundle.
- Avoid wildcards in trigger phrases (
illuminate/support version
not illuminate/* version) unless the original full phrase is
also present.
Required ingredients:
- Lead with the action. "Use when …" / "Reviews …". Drop
articles and filler ("Helps maintainers", "any project", "for
any").
- Scenarios the skill applies to.
- Trigger phrases after
Activates: — natural-language phrases
a user would type. Include verbs (writing, drafting,
auditing) and nouns the user would actually use. Comma-separated.
Split into Activates: {scenarios}; mentions: {user phrases} for
readability.
- Guardrail prefix. For skills that must run before other work
(collision-prevention, irreversible-edit safety), prefix with
MUST USE when ….
Pattern:
description: "Use when {trigger}. {Short what-it-covers, optional.}
Activates: {scenario 1}, {scenario 2}; mentions: {phrase 1},
{phrase 2}, {phrase 3}."
For a guardrail skill:
description: "MUST USE when {trigger}. {What it prevents.} Activates:
{file-path triggers}, {scenarios}; mentions: {phrases}."
Trim rules (apply to prose, not triggers): no articles (a/an/the),
no filler (just/really/any), short synonyms (covers not teaches you about), drop the project scope when implied.
Look at sibling shipped skills (readme, upgrading,
release-notes) for working examples.
4. Skill body structure
Minimum skeleton:
---
name: my-skill
description: "…"
---
# My Skill
One-paragraph framing — what the skill is, what it isn't.
## When to use this skill
- Bullet list of concrete situations.
## {Topic 1}
Instructions.
## {Topic 2}
Instructions.
Optional references/ subdirectory — drop ecosystem-specific or
deep-dive material there and link from the body. Used by the
readme, release-notes, and upgrading shipped skills for
Laravel-package-specific guidance. boost sync propagates
the whole references/ subtree alongside SKILL.md.
5. Run sync after every edit
vendor/bin/boost sync
This regenerates the per-agent skill directories. Skipping it leaves
agents reading stale content.
Commit the generated files together with the source. They ship
with the package and the --check mode will fail CI if they drift.
Checklist
