Skill descriptions missing trigger guidance — pipeline sub-skills and user-facing skills

[froesef]

Problem

An audit of the skills installed from plugins/aem/edge-delivery-services/skills/ found two categories of description quality issues that affect how reliably an agent selects the right skill.

Skill descriptions are used as routing signals — the agent loads a skill when its description matches the user intent. Descriptions that do not lead with Use this when… or lack any trigger phrasing cause two failure modes:

• The skill is never loaded when it should be
• The skill is loaded when it should not be

---

Category 1 — No trigger guidance at all (8 skills)

These descriptions open with a statement of what the skill does, not when to invoke it.

Skill	Current opening	Problem
authoring-analysis	"Analyze content sequences…"	No trigger, no invocation criteria
block-inventory	"Survey available blocks…"	No trigger, no disambiguation
find-test-content	"Search for existing content pages…"	No trigger, no disambiguation from page-import
generate-import-html	"Generate structured HTML…"	Reads as an internal pipeline label
identify-page-structure	"Identify section boundaries…"	Reads as an internal pipeline label
page-decomposition	"Analyze content sequences within a section…"	Says "Invoked per section" but has no "do not invoke directly" guard
scrape-webpage	"Scrape webpage content…"	No trigger, no disambiguation from playwright-cli
x-search	"Search X (formerly Twitter)…"	No trigger phrases

---

Category 2 — Trigger buried or weakly phrased (11 skills)

These have a Use this when clause but it is not the opening line, or the phrasing is too vague.

analyze-and-plan, block-collection-and-party, building-blocks, code-review, content-modeling, da-auth, da-content, preview-import, slicc-handoff, snowflake, testing-blocks, docs-search

Common issues:

• Description opens with a noun phrase ("Guide for…", "Reference for…") instead of a trigger
• Use this when appears mid-description after a feature summary
• Vague scope like "anytime you are developing something"
• No disambiguation from closely related skills (e.g. building-blocks vs content-driven-development)

---

Recommendation

For pipeline sub-skills

authoring-analysis, block-inventory, generate-import-html, identify-page-structure, page-decomposition, scrape-webpage are all explicitly invoked by page-import as numbered pipeline steps. Their descriptions should either:

• Open with Use this when… plus clear user-facing trigger phrases, or
• Add an explicit Do not invoke directly — called by page-import note so the agent does not accidentally load them in isolation

For all skills

Descriptions should follow the pattern:

Use this when <user-facing trigger>. Covers <topics>. [For <adjacent topic> use <sibling skill>.]

The Use this when clause must be the first sentence, not buried after a feature summary.

---

Reference

Skill description authoring guidance: skill-authoring SKILL.md in the SLICC runtime.