Skill descriptions missing trigger guidance — pipeline sub-skills and user-facing skills
- Dominant language
- JavaScript
- Stars
- 182
- Forks
- 73
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 35
Description
## 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 . Covers . [For use .]
```
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.
Contributor guide
Research direction
Review the listed skill descriptions under plugins/aem/edge-delivery-services/skills/ and read skill-authoring SKILL.md in the SLICC runtime first. Update the affected descriptions so the first sentence gives user-facing trigger guidance, or explicitly marks pipeline sub-skills as not directly invokable. Done means all listed Category 1 and Category 2 skills follow the stated pattern and distinguish adjacent skills where needed.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100