adobe / adobe/skills

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

Open
#215 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.