docs: add headless component authoring skill

[Dmytro Kirpa (dmytrokirpa)]

Summary

• add a Copilot skill for authoring and extending headless v9 component primitives
• document base-hook, data-attribute, packaging, bundle-size, test, Storybook, CSS Module, and accessibility requirements
• define a three-PR gh stack workflow separating component-package tests, base APIs from the dependent headless package
• register the skill for Copilot and Claude entry points

Validation

• verified all documented headless library, stories, and docsite Nx targets exist
• verified installed gh stack and Beachball flags used by the workflow
• checked skill metadata, mirror pointer, portable paths, and diff formatting

No Beachball change file is required because this change does not modify a published package.

[github-actions]

📊 Bundle size report

✅ No changes found

[github-actions]

Pull request demo site: URL

[Copilot]

Pull request overview

Adds guidance for authoring and extending headless Fluent UI v9 components.

Changes:

• Documents implementation, testing, packaging, and accessibility requirements.
• Defines stacked-PR and validation workflows.
• Registers the skill for Copilot and Claude.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
AGENTS.md	Registers the new slash command.
.agents/skills/headless-component/SKILL.md	Defines the authoring workflow and requirements.
.claude/skills/headless-component/SKILL.md	Adds the Claude skill pointer.

Suppressed comments (3)

.agents/skills/headless-component/SKILL.md:467

• Headless and v9 stories intentionally keep interaction assertions in tests rather than Storybook play functions. Requiring play here would make generated stories violate that convention; keep the story interactive/demonstrable and put the role, ARIA, data-state, and inverse-action assertions in unit or Cypress coverage.

7. Exercise the primary interaction instead of rendering only static variants.
   Interactive stories should drive the real component behavior and assert the
   resulting role/ARIA/data state in a `play` function. Cover the inverse action
   too; if the behavior requires a real browser primitive unavailable to the
   Storybook test runner, cover it in Cypress and keep the story demonstrable.

.agents/skills/headless-component/SKILL.md:571

• This preview package is currently 0.2.4 and follows zero-semver: new headless components have shipped as patches (for example TagPicker and MenuButton in library/CHANGELOG.md:12-28). minor would incorrectly advance 0.2.x to 0.3.0 for a normal additive primitive.

yarn beachball change --no-commit --branch master \
  --package @fluentui/react-headless-components-preview --type minor \
  --message "feat(react-headless-components-preview): add <ComponentName>"

.agents/skills/headless-component/SKILL.md:591

• This rule incorrectly assigns minor to new primitives in the 0.x headless preview package. Keep minor for new exports in stable v9 component packages, but use patch for additive headless-preview APIs under its zero-semver policy; otherwise future skill runs will create the wrong release bump.

- New public base exports and new headless primitives are normally `minor`
  changes. Use `patch` only when correcting an existing contract without adding
  public API, and never use `major` without explicit approval.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.agents/skills/headless-component/SKILL.md:575

• Beachball already records the package name, and the adjacent headless example uses the package-agnostic feat: form. Drop the repeated package scope here so the generated release note stays concise and consistent.

  --message "feat(react-<name>): expose headless base APIs"

.agents/skills/headless-component/SKILL.md:84

• The PR description says this skill defines a two-PR component/headless stack, but this requirement adds a third regression-test PR and the workflow section repeats that three-PR shape. Please align the PR description and documented workflow so contributors know which stack is intended.

7. Plan the change as three stacked PRs before editing:
   - **bottom PR — regression test:** lock down the existing behavior that the
     base extraction must preserve; do not change production code