feat: rules and skills by marissahuysentruyt · Pull Request #6050 · adobe/spectrum-web-components

marissahuysentruyt · 2026-02-24T17:31:06Z

Description

This PR adds Cursor agent skills and refactors existing AI instructions into the rule/skill structure within the .cursor directory. It introduces reusable, documented skills for common workflows (accessibility, docs, commits, migration, handoff, testing) and an always-applied deep-understanding rule, and updates .cursor documentation accordingly.

NOTE: not all skills have been tested. We can continue to refine these documents, however, after we've tried to use them in realistic workflows and settings.

New skills

accessibility-compliance: WCAG 2.2–oriented guidance with ARIA patterns, mobile accessibility, and reference docs (aria-patterns.md, mobile-accessibility.md, wcag-guidelines.md).
ask-questions: When and how to clarify requirements before implementing.
component-migration-rendering-styling: Creating rendering-and-styling migration analysis for 2nd-gen components.
contributor-docs-nav: Running the CONTRIBUTOR-DOCS nav script (breadcrumbs, TOCs, link checks).
conventional-commits: Writing conventional commit messages.
deep-understanding: Scoping, deep read, persistent research.md, pause for review, then implement (used by the always-applied rule).
documentation: Following Adobe content writing standards when writing docs.
explain-code: Explaining code with diagrams and analogies.
session-handoff: Creating handoff docs, resume checklists, and scripts (create_handoff.py, validate_handoff.py, list_handoffs.py, check_staleness.py) plus evals and references.
test-driven-development: TDD workflow and testing anti-patterns reference.

☝️ Any skills linked above were externally written/created, but may have been tweaked to fit our needs more specifically (i.e. writing to a .cursor folder instead of .claude)

Rules and docs

Deep-understanding rule: Always applied; requires research and a written artifact before planning or code.
AI agent instructions moved into the rule/skill model.
.cursor/README.md: Updated to describe newer rules and the new skills (with brief descriptions and when to use each).

Motivation and context

Consistency: Centralize AI behavior in skills and rules so Cursor follows the same patterns (docs, a11y, commits, migration, handoffs, TDD).
Discoverability: Document skills in the README so contributors know what’s available and when to use it.
Quality: Deep-understanding as a rule reduces “signature-level” work and encourages research and a reviewable artifact before implementation.
Maintainability: Session-handoff skill and scripts improve context transfer and long-running work across sessions.

Open questions

Currently, our AI rules assume that everyone is using Cursor. This might mean that the rules and skills won't automatically be used if a contributor/team mate isn't using Cursor.

❓ Should we also create a small section in the .cursor/README or even the project's README to explain that non-Cursor users can copy the rules and skills contents into their own local IDE-specific directory (like .vscode) so they get the rules/skills automatically as well?

Related issue(s)

addresses SWC-1503 (CSS conventions)
addresses SWC-1505 (accessibility requirements)
partially addresses SWC-1498 and SWC-1506 (washing machine workflow), as well as SWC-1537 (AI-friendly documentation epic)
addresses SWC-1605

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed the Accessibility Practices for this feature, see: Aria Practices
I have added automated tests to cover my changes.
I have included a well-written changeset if my change needs to be published.
I have included updated documentation if my change required it.

Reviewer's checklist

Includes a Github Issue with appropriate flag or Jira ticket number without a link
Includes thoughtfully written changeset if changes suggested include patch, minor, or major features

Manual review test cases

Skills and rules appear in repo
- Open the repo in Cursor with this branch.
- Confirm .cursor/skills/* and .cursor/rules/* are present
- Expect no broken paths or missing files
- Reading the rules .mdc files and skills SKILL.md files still make understandable sense to humans. (i.e. does the skill make enough sense that you understand what the agent should do?)
Documentation is coherent
- Read .cursor/README.md sections for rules and skills.
- Expect clear, consistent descriptions and correct references to skill paths.

Additional validation

Feel free to test any of the new skills or rules! For instance...

Session-handoff skill runs & works
- With the branch pulled down locally, open a past chat (preferably one where you ran the context window quite high).
- If possible in that chat, @ mention the session-handoff skill or say something to the affect of "context is getting full" or "create handoff." You should see the agent working with something like this:

Verify a session handoff is created (named something like "2026-02-24-141544-cursor-rules-skills-docs.md") is created in a .cursor/handoffs directory. Once the agent is done, it should give you a brief summary of the handoff doc and steps for the next session/chat.
Start a new session or chat, and resume your work by saying something like "resume from handoff" or "load handoff." You should see something like this once the agent has gotten the context from the old session:

changeset-bot · 2026-02-24T17:31:12Z

⚠️ No Changeset found

Latest commit: 36a3c47

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2026-02-24T17:37:28Z

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-6050

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

rise-erpelding

These look really nice! As is appropriate for this day and age, I had AI do some analysis here and pointed out a few things it noticed. I wouldn't consider any of it blocking though, since AI would be able to get around any minor inconsistencies, and I think having something here is better than nothing.

rise-erpelding · 2026-02-25T19:49:59Z

.cursor/skills/contributor-docs-nav/SKILL.md

+
+For complete Operator and Maintainer workflows, debugging, link-verification handling, script behavior details, and the testing checklist, read:
+
+**CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/01_ai-agent-instructions.md**


This doesn't have to be a decision we make here and now, but bringing up here the thought that I had before about where this 01_ai-agent-instructions.md should live. To me, this file is a skill that we had before we knew to call it a skill, and we could move its contents up into this file to keep things a bit clearer.

Agreed! I've moved it up to this directory under reference/ai-agent-instructions.md.

When I was chatting with Cursor it brought up a good point that the original directory in CONTRIBUTOR-DOCS was a little confusing/deceiving since there were both computer/AI docs alongside human docs. I think moving it makes sense.

rise-erpelding · 2026-02-25T19:52:24Z

.cursor/skills/component-migration-rendering-styling/SKILL.md

+
+For the exact document structure, heading levels, collapsible sections, CSS⇒SWC mapping table format (columns, status values, ordering), DOM comparison format, and output format notes, read:
+
+**CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/cursor_prompt.md**


Same question for this as well as with 01_ai-agent-instructions, is there an appetite for moving the reusable prompt up and officially calling it a skill?

yyyyessss doing it.

.cursor/skills/session-handoff/evals/model-expectations.md

rise-erpelding · 2026-02-25T20:10:34Z

.cursor/skills/session-handoff/evals/setup_test_env.py

Makes sense to me to put scripts here, but now I have a follow up question to my earlier question about moving the CONTRIBUTOR-DOCS agent instructions into skills, if we did that, should we move the update-nav.js script (and the other script there) into .cursor/ as well?

I did this! We have a scripts and reference directory in contributor-docs-nav now.

Open for discussion the naming. 🤔

rise-erpelding · 2026-02-25T20:20:29Z

.cursor/skills/session-handoff/SKILL.md

+python scripts/create_handoff.py [task-slug]
+```
+
+Example: `python scripts/create_handoff.py implementing-user-auth`


Should these examples specify the full path? For instance

Suggested change

Example: `python scripts/create_handoff.py implementing-user-auth`

Example: `python .cursor/skills/session-handoff/scripts/create_handoff.py implementing-user-auth`

When I had agents (via Codex & Cursor) see if there was anything here that was problematic, they both flagged this. My understanding is that the skills would be applied from the repo root, not from where the skill is located, thus why the agents are flagging this as a potential issue.

I assumed that session handoff would still work fine because AI could figure this out - which is true. I tried a session handoff (which it kinda bungled because I was on your branch and not the branch I had done the rest of the stuff from the chat I asked it to create session-handoff from), and then I asked it some questions about how it did it, and it confirmed that it had to search for the scripts then run them from the full path from .cursor/.

FWIW it's also pointing out the Python version, it's running python3 - that feels less significant.

Those should be fixed in several places in the file now!

.cursor/skills/session-handoff/SKILL.md

.cursor/skills/session-handoff/scripts/validate_handoff.py

rise-erpelding · 2026-02-25T21:06:48Z

.cursor/skills/conventional-commits/SKILL.md

+| `build`    | Build system or CI changes            |
+| `chore`    | Routine maintenance tasks             |
+| `ci`       | Continuous integration configuration  |
+| `deps`     | Dependency updates                    |


Do we ever use this deps type? (I feel like our team tends to use chore instead.)

We don't list deps in branch-naming.mdc or in .cursor/config.json.

I'm wondering if there should be a single source of truth for all the types as well? Like this skill and the branch-naming rule should both refer to the config.json instead of re-listing all the types again?

I removed the deps, and added some more documentation around using the config.json.

.cursor/rules/deep-understanding.mdc

blunteshwar · 2026-03-03T13:04:51Z

.cursor/skills/accessibility-compliance/references/aria-patterns.md

+
+```tsx
+function Tabs({ tabs }) {
+    const [activeIndex, setActiveIndex] = useState(0);


How about we tweak the examples to better fit the LIT context since we’re using LIT in SWC? Right now, many examples seem to be using React.

Let me know what you think of the new examples! Cursor rewrote them.

.cursor/skills/session-handoff/scripts/check_staleness.py

.cursor/skills/session-handoff/scripts/create_handoff.py

.cursor/README.md

cdransf

This looks great! Just one question. ✨

cdransf · 2026-03-04T22:40:58Z

.cursor/skills/accessibility-compliance/references/mobile-accessibility.md

+}
+```
+
+## iOS VoiceOver


Should we remove the iOS/Android/native section of this skill?

blunteshwar · 2026-03-05T06:22:27Z

Once ci is green I think we are good to merge

- accessibility compliance - explain code - documentation standards - session handoff - test-driven-development

Co-authored-by: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com>

marissahuysentruyt self-assigned this Feb 24, 2026

marissahuysentruyt added Component:Tooling Issue or PR dealing with scripts, workflows, automation, etc. Component prefix is for Jira Status:Ready for review PR ready for review or re-review. labels Feb 24, 2026

marissahuysentruyt marked this pull request as ready for review February 24, 2026 19:31

marissahuysentruyt requested a review from a team as a code owner February 24, 2026 19:31

rise-erpelding reviewed Feb 25, 2026

View reviewed changes

blunteshwar requested changes Mar 3, 2026

View reviewed changes

marissahuysentruyt force-pushed the marissahuysentruyt/feat-agent-skills branch from a131d45 to 3642b55 Compare March 4, 2026 20:31

marissahuysentruyt requested review from blunteshwar and rise-erpelding March 4, 2026 22:18

marissahuysentruyt added Status:Ready for re-review PR has had its feedback addressed and is once again ready for review. and removed Status:Ready for review PR ready for review or re-review. labels Mar 4, 2026

cdransf approved these changes Mar 4, 2026

View reviewed changes

blunteshwar approved these changes Mar 5, 2026

View reviewed changes

marissahuysentruyt added 13 commits March 5, 2026 10:03

feat: new agent skills added

4a43b6b

- accessibility compliance - explain code - documentation standards - session handoff - test-driven-development

feat: add conventional commit skill

310b6c7

feat: add ask question skill

40bc612

docs: fix double extension

78f1084

docs(cursor): update rules README

f5fd5a0

docs: refactor ai-agent-instructions to rule/skill

6dd613e

docs(cursor): update cursor README with skills

1a1a3f4

feat: add component migration skill

2465549

feat: add deep understanding skill/rule

5f75fd6

fix: pathing

07593d8

docs: mcp blurb

e91370d

fix: session handoff directory

7891120

docs: update readme to reflect non-cursor usage

209ebd6

marissahuysentruyt and others added 15 commits March 5, 2026 10:03

docs: update heading level matching in session-handoff

730b08d

Co-authored-by: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com>

chore: make deepunderstanding applied intelligently

9eac91f

chore: update handoff references claude > cursor

d4f640b

docs: deepunderstanding skill applies intelligently

3905241

chore: cursor wanted clarification on jira/github labels

6b23df4

docs: cursor rules/skills readme

38b59be

chore: add handoffs to gitignore

07eb2f8

fix: use lit examples instead of react

4169d3e

fix: session-hand off script path

a4c5999

docs: move ai-agent-instructions to skills

1450de3

fix: broken links

b1fd263

docs: move migration prompt to skills

4333347

fix: heading level match validation

b053a03

Co-authored-by: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com>

docs: remove deps commit type

deda699

fix: removed ios/android mobile sections in a11y skill

5d20b9e

marissahuysentruyt force-pushed the marissahuysentruyt/feat-agent-skills branch from 83cf8f2 to 5d20b9e Compare March 5, 2026 15:04

style: linting

36a3c47

marissahuysentruyt merged commit 50a4816 into main Mar 5, 2026
23 checks passed

marissahuysentruyt deleted the marissahuysentruyt/feat-agent-skills branch March 5, 2026 17:13


		For complete Operator and Maintainer workflows, debugging, link-verification handling, script behavior details, and the testing checklist, read:

		CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/01_ai-agent-instructions.md


		For the exact document structure, heading levels, collapsible sections, CSS⇒SWC mapping table format (columns, status values, ordering), DOM comparison format, and output format notes, read:

		CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/cursor_prompt.md

	Example: `python scripts/create_handoff.py implementing-user-auth`
	Example: `python .cursor/skills/session-handoff/scripts/create_handoff.py implementing-user-auth`

Conversation

marissahuysentruyt commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Open questions

Related issue(s)

Author's checklist

Reviewer's checklist

Manual review test cases

Additional validation

Uh oh!

changeset-bot bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

Uh oh!

rise-erpelding left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cdransf left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blunteshwar commented Mar 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

marissahuysentruyt commented Feb 24, 2026 •

edited

Loading

changeset-bot bot commented Feb 24, 2026 •

edited

Loading

github-actions bot commented Feb 24, 2026 •

edited

Loading