skills: carry when_to_use trigger text into Cursor, which ignores the key

Parent

Problem

Cursor ignores the when_to_use skill frontmatter key. When our plugins load in Cursor, each skill is listed with only its description. A trigger phrase kept in when_to_use never reaches the model, so automatic invocation in Cursor loses it.

Probe, Cursor CLI 2026.10.19-6bbf2c4, 2026-11-02: a phrase placed only in when_to_use was absent from the skill's listing entry, and the description was present.
Docs: https://cursor.com/docs/skills.md lists the skill frontmatter fields as name, description, paths, disable-model-invocation, icon, color and metadata. when_to_use is not among them.

Affected skills on main today (3): computer-use/skills/diagnose, playwright/skills/demo-video and playwright/skills/playwright.

Outcome

Decide how a skill's trigger text reaches Cursor without a fork or Cursor-specific files. Options include moving it into description or keeping when_to_use and accepting the loss. Then apply the decision and record it in the skill-authoring guidance.

Out of scope

Cursor-specific files or a forked plugin.

Done when

Decision: comment.

In plugins/computer-use/skills/diagnose/SKILL.md, plugins/playwright/skills/demo-video/SKILL.md and plugins/playwright/skills/playwright/SKILL.md, the trigger text moves into description and when_to_use is gone.
The skill-authoring guidance says trigger text goes in description.
plugins/skill-quality/scripts/check-listing-budget.sh and check-skill.sh pass on the changed skills, with text shortened rather than exempted.
A follow-up issue is filed for the other four skills that use when_to_use (skill-quality check, harness-ops audit-native-overlap and inventory, session-flow recommend-skills).

Proposed work class: work-class: scoped
Basis: automated intake triage; the lanes App applied this class.

Size: Small
Complexity: Low
Uncertainty: Known
Flags: none
Blocked by: none

Understood: Cursor ignores when_to_use, so trigger text for three skills (computer-use diagnose, playwright demo-video and playwright) should move into description. The authoring guidance should say so, and a follow-up issue should be filed for the other four skills.

Decision recorded.
Agent choice, not an owner answer.

This records the choice Lane 2 made in comment 6588069406 on 2026-11-02T20:47Z, so the issue can return to admission.
[quote truncated; the full decision is at the link]

Decision: #12482 (comment)

The decision settles the open question (move trigger text into description, drop when_to_use for the three skills, follow-up for the rest). Nothing further is asked. No duplicates found.

_{Automated triage, applied by the lanes App.}

The latest triage verdict holds nothing: admission moved the issue to status: needs-decision; its comment says why.

Refinement. A read-only run explored this repository, searched its issues and pull requests, and read the allowed docs to draft what follows. On an issue a listed human filed, it counts as the issue's spec once posted, while unedited; it is still model text, so check it.

Intended outcome: Fold the trigger text of the three skills' when_to_use into description (keeping the listing budget), and record in the skill-authoring guidance that Cursor ignores when_to_use.

Related work

Concise skills: one skill-creation standard, evals, and a fleet-wide rollout #6476 (related): Concise-skills standard and fleet rollout; any description rewrite should follow its skill-creation standard.
perf: cut the bodies of the most-invoked skills through progressive disclosure #12240 (related): Skill-body progressive disclosure work that touches the same skills and may conflict on edits.

Open questions

Should the trigger text move into description (merging when_to_use into it for the 3 skills), or should when_to_use stay and the Cursor loss be accepted?
RECOMMENDED: Move it into description for the three affected skills, and drop when_to_use there. Basis: Cursor documents description as supported and the probe showed it reaches the listing; the three keys are at plugins/computer-use/skills/diagnose/SKILL.md:3, plugins/playwright/skills/demo-video/SKILL.md:3, plugins/playwright/skills/playwright/SKILL.md:3
Should the rule apply to all skills (guidance says put trigger text in description going forward), including the four other skills that use when_to_use (skill-quality check, harness-ops audit-native-overlap and inventory, session-flow recommend-skills)?
RECOMMENDED: Make it a general rule in the guidance, but only change the three named skills in this issue; leave the other four to a follow-up. Basis: judgment
Does merging into description risk exceeding the listing budget or the description length limits enforced by the repo's checks?
RECOMMENDED: Apply the merge and require that the listing-budget and skill checks still pass; if a skill goes over, shorten the text rather than exempting it. Basis: plugins/skill-quality/scripts/check-listing-budget.sh

Sources read

plugins/computer-use/skills/diagnose/SKILL.md:3: when_to_use holds the trigger text for diagnose
plugins/playwright/skills/demo-video/SKILL.md:3: when_to_use holds the trigger phrases for demo-video
plugins/playwright/skills/playwright/SKILL.md:3: when_to_use holds the trigger phrases for playwright
plugins/playbooks/CHANGELOG.md:1316: the only mention of when_to_use in playbooks markdown; skill-authoring guidance does not currently document the key
plugins/skill-quality/scripts/check-listing-budget.sh: tooling that counts when_to_use toward the listing budget

To answer, post a comment that starts with this line:

**Decision recorded.** <answer>

_{Automated refinement by the lanes App. Answer with a comment whose first line is **Decision recorded.**.}

Agent choice, not an owner answer. The owner did not answer this question. Lane 2 chose on the #7556 evidence, and Issue Triage owns the question. Accept the triage recommendations. (1) Move the trigger text into description for the three skills (computer-use diagnose, playwright demo-video and playwright) and drop when_to_use there. Basis: the #7556 probe showed Cursor reads description and ignores when_to_use. (2) The skill-authoring guidance says trigger text goes in description. The other four skills that use when_to_use move in a follow-up issue this PR files. (3) The listing-budget and skill checks must still pass; shorten text rather than exempt a skill. Basis: plugins/skill-quality/scripts/check-listing-budget.sh. Decided under the owner's standing direction (decide from evidence; no intent, security or cost question here).

This records a re-fire of an earlier refusal, not a new refusal. The lanes kill switch stopped run 41522463663, the work-resolve-issue run that agent-ready started, before it did any work; that run ended at 2026-11-02T20:53:57Z. work-unblock has now removed and added agent-ready back to start a fresh run. A kill-switch refusal is no fault in this issue or the lanes, so it never counts against later re-fires; after limits.limit-stops-per-issue of them since a person last added agent-ready or a run last reported, work-unblock waits longer before each one, up to 24 hours.

The work-resolve-issue lane stopped partway through this issue and needs a person.

Reason: security

Why, in the run's own words:

The run did not start: the issue's title or body changed after agent-ready was added, so the runner wrote no issue file for the skill and no model ran.

Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/41532046031

To retry, remove needs-human and add agent-ready again.

Decision recorded.
Agent choice, not an owner answer.

This records the choice Lane 2 made in comment 6588069406 on 2026-11-02T20:47Z, so the issue can return to admission. That comment opened with "Agent choice" instead of the **Decision recorded.** line the refinement asks for, so the hold stayed on.

The choice accepts the three refinement recommendations. Move the trigger text into description for the three skills that use when_to_use (computer-use diagnose, playwright demo-video and playwright) and drop when_to_use there. Basis: the #7556 probe showed Cursor reads description and ignores when_to_use. The skill-authoring guidance says trigger text goes in description. The other four skills that use when_to_use move in a follow-up issue that this work files. The listing-budget and skill checks must still pass, with text shortened rather than a skill exempted.

None of the owner's three reasons applies: the choice keeps the issue's intent, finds nothing that changes the primary design, and touches no secret, account or billing boundary. The one security stop on this issue (comment 6590416728) was the runner refusing a body edited after agent-ready was added, not a security finding.

On origin/main at f534b38140, when_to_use: appears at line 3 of each of the three SKILL.md files below, and the skill-authoring guidance lives under plugins/playbooks/skills/skill-authoring/ (SKILL.md, reference/skill-criteria.md).

In plugins/computer-use/skills/diagnose/SKILL.md, plugins/playwright/skills/demo-video/SKILL.md and plugins/playwright/skills/playwright/SKILL.md, the trigger text moves into description and when_to_use is gone.
The skill-authoring guidance under plugins/playbooks/skills/skill-authoring/ says trigger text goes in description.
plugins/skill-quality/scripts/check-listing-budget.sh and plugins/skill-quality/scripts/check-skill.sh pass on the changed skills, with text shortened rather than exempted.
A follow-up issue is filed for the other four skills that use when_to_use (skill-quality check, harness-ops audit-native-overlap and inventory, session-flow recommend-skills).

Not admitted to the issue lane: its done-when asks for what an unattended lane run cannot perform: item 4 (a tracker write instead of a file change: "A follow-up issue is filed for the other four skills that use when_to_use (sk..."), item 8 (a tracker write instead of a file change: "A follow-up issue is filed for the other four skills that use when_to_use (sk..."); recommended split: keep the other items here as the admissible issue and move these to a child issue for the host queue (host-run). Admission takes the issue once each of those is met, when intake triages it again (.github/actions/resolve-config/admission-rules.json).

Navigation Menu

Repository navigation

skills: carry when_to_use trigger text into Cursor, which ignores the key #12482

Parent

Problem

Outcome

Out of scope

Done when

4 remaining items

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

skills: carry when_to_use trigger text into Cursor, which ignores the key #12482

Description

Parent

Problem

Outcome

Out of scope

Done when

Activity

github-actions commented on Nov 2, 2026

melodic-automation-lanes commented on Nov 2, 2026

melodic-automation-lanes commented on Nov 2, 2026

kyle-sexton commented on Nov 2, 2026

melodic-automation-lanes commented on Nov 2, 2026

4 remaining items

melodic-automation-lanes commented on Nov 2, 2026

kyle-sexton commented on Nov 3, 2026

melodic-automation-lanes commented on Nov 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions