docs: improve S2 agent skill

packages/dev/s2-docs/scripts/generateAgentSkills.mjs

@@ -75,6 +75,31 @@ const SKILLS = {
   }
 };
 
+const CUSTOM_SKILL_CONTENT = {
+  'react-spectrum-s2': {
+    skillNotesMarkdown:
+      'If the requirements do not clearly specify which React Spectrum component to use, consult the [Component Decision Tree](references/guides/component-decision-tree.md) before choosing a component.',
+    embeddedMarkdownPaths: [
+      path.join(
+        REPO_ROOT,
+        'packages/dev/s2-docs/skills/react-spectrum-s2/implementation-guidance.md'
+      )
+    ],
+    guideEntries: [
+      {
+        title: 'Component Decision Tree',
+        path: 'component-decision-tree.md',
+        sourcePath: path.join(
+          REPO_ROOT,
+          'packages/dev/s2-docs/skills/react-spectrum-s2/component-decision-tree.md'
+        ),
+        description:
+          'How to choose the right S2 component when requirements do not name one explicitly.'
+      }
+    ]
+  }
+};
+
 /**
  * Ensure markdown docs are generated
  */
@@ -100,6 +125,45 @@ function getWellKnownRootForLibrary(sourceDir) {
   );
 }
 
+function getCustomSkillContent(skillName) {
+  return CUSTOM_SKILL_CONTENT[skillName] ?? null;
+}
+
+function renderCustomMarkdown(markdownPath, replacements = {}) {
+  let content = fs.readFileSync(markdownPath, 'utf8');
+  for (const [token, value] of Object.entries(replacements)) {
+    content = content.replaceAll(token, value);
+  }
+  return content.trim();
+}
+
+function readCustomEmbeddedMarkdown(skillName, replacements = {}) {
+  const customContent = getCustomSkillContent(skillName);
+  if (!customContent?.embeddedMarkdownPaths?.length) {
+    return '';
+  }
+
+  return customContent.embeddedMarkdownPaths
+    .flatMap((markdownPath) => {
+      if (!fs.existsSync(markdownPath)) {
+        console.warn(`Custom skill content not found at ${markdownPath}`);
+        return [];
+      }
+
+      return [renderCustomMarkdown(markdownPath, replacements)];
+    })
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+function getCustomGuideEntries(skillName) {
+  return getCustomSkillContent(skillName)?.guideEntries ?? [];
+}
+
+function getCustomSkillNotesMarkdown(skillName) {
+  return getCustomSkillContent(skillName)?.skillNotesMarkdown ?? '';
+}
+
 /**
  * Parse llms.txt to get documentation entries
  */
@@ -316,34 +380,48 @@ metadata:
  * Generate the SKILL.md content
  */
 function generateDocsSkillMd(skillConfig, categories, isS2) {
+  const customGuideEntries = getCustomGuideEntries(skillConfig.name);
+  const customSkillNotesMarkdown = getCustomSkillNotesMarkdown(skillConfig.name);
+  const embeddedCustomMarkdown = readCustomEmbeddedMarkdown(skillConfig.name, {
+    '{{guidesBase}}': 'references/guides/',
+    '{{componentsBase}}': 'references/components/'
+  });
+
   let content = generateFrontmatter(skillConfig);
 
   if (isS2) {
     content += `# React Spectrum S2 (Spectrum 2)
 
 React Spectrum S2 is Adobe's implementation of the Spectrum 2 design system in React. It provides a collection of accessible, adaptive, and high-quality UI components.
-
-## Documentation Structure
-
-The \`references/\` directory contains detailed documentation organized as follows:
-
 `;
   } else {
     content += `# React Aria Components
 
 React Aria Components is a library of unstyled, accessible UI components that you can style with any CSS solution. Built on top of React Aria hooks, it provides the accessibility and behavior without prescribing any visual design.
+`;
+  }
+
+  if (customSkillNotesMarkdown) {
+    content += `\n${customSkillNotesMarkdown}\n`;
+  }
+
+  if (embeddedCustomMarkdown) {
+    content += `\n${embeddedCustomMarkdown}\n\n`;
+  }
 
-## Documentation Structure
+  content += `## Documentation Structure
 
 The \`references/\` directory contains detailed documentation organized as follows:
 
 `;
-  }
 
   // Add documentation sections
-  if (categories.guides.length > 0) {
+  if (customGuideEntries.length > 0 || categories.guides.length > 0) {
     content += `### Guides
 `;
+    for (const entry of customGuideEntries) {
+      content += `- [${entry.title}](references/guides/${entry.path})${entry.description ? `: ${entry.description}` : ''}\n`;
+    }
     for (const entry of categories.guides) {
       content += `- [${entry.title}](references/guides/${entry.path})${entry.description ? `: ${entry.description}` : ''}\n`;
     }
@@ -524,10 +602,11 @@ Use these when you need more component-by-component or API-level detail:
 function copyDocsDocumentation(skillConfig, categories, skillDir) {
   const refsDir = path.join(skillDir, 'references');
   const sourceDir = path.join(MARKDOWN_DOCS_DIST, skillConfig.sourceDir);
+  const customGuideEntries = getCustomGuideEntries(skillConfig.name);
 
   // Create subdirectories only if they have content
   const subdirs = [
-    {name: 'guides', entries: categories.guides},
+    {name: 'guides', entries: [...customGuideEntries, ...categories.guides]},
     {name: 'components', entries: categories.components},
     {name: 'interactions', entries: categories.interactions},
     {name: 'utilities', entries: categories.utilities},
@@ -559,6 +638,28 @@ function copyDocsDocumentation(skillConfig, categories, skillDir) {
   };
 
   // Copy guides
+  const customContent = getCustomSkillContent(skillConfig.name);
+  for (const entry of customGuideEntries) {
+    const sourcePath =
+      entry.sourcePath ||
+      customContent?.embeddedMarkdownPaths?.find((markdownPath) =>
+        markdownPath.endsWith(entry.path)
+      );
+    if (!sourcePath || !fs.existsSync(sourcePath)) {
+      continue;
+    }
+
+    const targetPath = path.join(refsDir, 'guides', entry.path);
+    fs.mkdirSync(path.dirname(targetPath), {recursive: true});
+    fs.writeFileSync(
+      targetPath,
+      renderCustomMarkdown(sourcePath, {
+        '{{guidesBase}}': '',
+        '{{componentsBase}}': '../components/'
+      }) + '\n'
+    );
+  }
+
   for (const entry of categories.guides) {
     copyFile(entry, 'guides');
   }

packages/dev/s2-docs/skills/react-spectrum-s2/component-decision-tree.md

@@ -0,0 +1,117 @@
+## Component Decision Tree
+
+If the user does not specify which component they would like to use, choose one based on the requirements. Use the following as a guide:
+
+- Prefer an existing React Spectrum S2 component over a custom component.
+- Match the interaction model first, then the visual treatment.
+- Prefer the narrowest component that fits the requirement instead of a more general one.
+- If two components could work, choose the more standard and accessible pattern.
+- Reach for React Aria Components plus the S2 `style` macro only as a last resort when no S2 component fits the behavior or layout, or if the user specifically asks for a custom component.
+
+### Actions and navigation
+
+- Use `Button` for primary or secondary calls to action and prominent actions. It can also navigate.
+- Use `ActionButton` for lower-emphasis actions, toolbar actions, row actions, and compact icon-led actions.
+- Use `LinkButton` when the element should navigate like a link but look like a button.
+- Use `Link` for inline or standalone text navigation.
+- Use `ButtonGroup` or `ActionButtonGroup` only to group related buttons.
+- Use `ActionMenu` for a simple "more actions" ellipsis button that opens a menu.
+- Use `Menu` when the menu itself is the pattern, especially if you need sections, submenus, selection, links, or a custom trigger arrangement.
+- Use `ActionBar` for bulk actions within a collection component.
+
+### Choosing from options
+
+- Use `Switch` for turning a setting on or off.
+- Use `Checkbox` for a single independent yes or no option.
+- Use `CheckboxGroup` for multiple simple visible options where many may be selected.
+- Use `RadioGroup` for a small visible mutually exclusive list.
+- Use `SelectBoxGroup` when options should stay visible and need richer presentation such as illustrations, labels, or descriptions.
+- Use `Picker` for selecting from a collapsible list of known options when typing to search is not important.
+- Use `ComboBox` when the user should type to filter options, search a long list, or create an action from the current input.
+- Use `SegmentedControl` for a small mutually exclusive view or mode switch.
+- Use `ToggleButton` for a single pressed/unpressed control.
+- Use `ToggleButtonGroup` for compact formatting-style or tool-style toggles, especially if multi-select may be needed.
+
+### Text and value input
+
+- Use `TextField` for single-line plain text input.
+- Use `SearchField` for a search query with search-specific clear and submit behavior.
+- Use `TextArea` for multi-line text.
+- Use `NumberField` for precise numeric entry and stepping.
+- Use `Slider` for adjusting one numeric value when direct manipulation is more important than exact typed entry.
+- Use `RangeSlider` for adjusting a numeric range.
+- Use `DateField` or `TimeField` when keyboard editing of a date or time is the main interaction.
+- Use `DatePicker` or `DateRangePicker` when a popover calendar should help with choosing dates.
+- Use `Calendar` or `RangeCalendar` when the calendar grid itself is needed without the input field or popover.
+- Use `ColorField` to edit a hex color or channel value directly.
+- Use `ColorSwatch` to display a chosen color.
+- Use `ColorSwatchPicker` to choose from predefined colors.
+- Use `ColorArea`, `ColorSlider`, and `ColorWheel` for direct color manipulation.
+
+### Collections and data views
+
+- Use `TableView` when users need rows and columns, dense comparison, sortable headers, cell-level content, editable cells, column resizing, or other tabular behaviors.
+- Use `ListView` for a flat list of records where each row is the main unit and may include icons, thumbnails, descriptions, and row actions.
+- Use `TreeView` when the hierarchy itself must stay visible and expandable in place.
+- Use `CardView` for visually rich collections of objects, galleries, or asset browsers with selection and bulk actions.
+- Use `TagGroup` for compact tags, tokens, or filters rather than general records.
+- Use `TableView` with expandable rows only if the tabular columns still matter after hierarchy is introduced.
+- Use `ListView` with `hasChildItems` and breadcrumbs for drill-in navigation when only one level is shown at a time.
+
+### `TableView` vs `ListView` vs `TreeView` vs `CardView`
+
+- Choose `TableView` if the user needs to compare fields across columns.
+- Choose `ListView` if the user needs a simple vertical list of records with optional secondary content and actions.
+- Choose `TreeView` if parent-child structure is the key mental model.
+- Choose `CardView` if preview imagery, card layouts, or gallery browsing matter more than dense comparison.
+
+### Cards
+
+- Use `Card` for one summarized object, not for an entire selectable collection.
+- Use `CardView` when many cards need keyboard navigation, selection, loading states, empty states, or bulk actions.
+- Prefer `AssetCard` for files, images, folders, documents, or other assets.
+- Prefer `UserCard` for people or profiles.
+- Prefer `ProductCard` for products or offers with a clear call to action.
+- Use `Card` with `CollectionCardPreview` for grouped assets or a preview collage.
+- Use a preview-only `Card` for gallery tiles in a waterfall-style presentation.
+- Use a custom `Card` only when the object is still clearly a card but the built-in layouts do not fit the content structure.
+
+### Structure and disclosure
+
+- Use `Tabs` when switching between peer sections of content and showing one panel at a time.
+- Use `SegmentedControl` instead of `Tabs` when switching app modes or views rather than full content panels.
+- Use `Disclosure` for one collapsible section.
+- Use `Accordion` for a group of related collapsible sections.
+- Use `Breadcrumbs` to show navigation depth or hierarchy location.
+- Use `Divider` to separate adjacent groups of content.
+
+### Overlays, help, and feedback
+
+- Use `Tooltip` for a short description of a focusable element. Do not rely on it for essential content.
+- Use `ContextualHelp` for additional explanation near content, especially for non-interactive or disabled UI.
+- Use `Popover` for interactive contextual content anchored to a nearby trigger when a modal is unnecessary.
+- Use `Dialog` for modal tasks or workflows.
+- Use `AlertDialog` for confirmations, destructive actions, and critical messages that must be acknowledged.
+- Use `FullscreenDialog` for complex workflows that need substantially more space.
+- Use `CustomDialog` only when the standard dialog layouts do not fit.
+- Use `InlineAlert` for a persistent non-modal message associated with content in the current view.
+- Use `Toast` for temporary global feedback after an action.
+
+### Status, loading, media, and empty states
+
+- Use `Badge` for compact color-coded metadata.
+- Use `StatusLight` for an object's current status.
+- Use `ProgressBar` or `ProgressCircle` for task progress over time.
+- Use `Meter` for a level or quantity within a known range when it is not task progress.
+- Use `Skeleton` for loading placeholders.
+- Use `Avatar` or `AvatarGroup` for people and participants.
+- Use `Image` for images that need loading and error handling.
+- Use `IllustratedMessage` for empty states or error pages.
+- Use `DropZone` for drag-and-drop file or object upload targets.
+- Use `Form` to provide layout, submission, and validation structure for grouped fields.
+
+### Last-resort custom components
+
+- Only create a custom component when no S2 component matches the required interaction pattern, or when the needed layout cannot be achieved by composing existing S2 components.
+- Build custom components with React Aria Components for behavior and accessibility, and the S2 `style` macro for Spectrum styling.
+- Do not bypass an existing S2 component just to apply unsupported visual customization.