Skip to content

feat: agent skills + migration guide improvements#725

Merged
sean-brydon merged 13 commits intomainfrom
pasquale/cui-154-agent-skills
Mar 23, 2026
Merged

feat: agent skills + migration guide improvements#725
sean-brydon merged 13 commits intomainfrom
pasquale/cui-154-agent-skills

Conversation

@pasqualevitiello
Copy link
Copy Markdown
Contributor

@pasqualevitiello pasqualevitiello commented Mar 22, 2026

Summary

Adds a comprehensive set of agent skills for coss UI following the agentskills.io specification, plus improvements to the Radix migration guide and component docs.

Changes recap:

  • content/docs: minor changes
  • lib/registry: refactored to make it work with shadcn v4
  • JSON files: can be skipped - shadcn v4 pushes type at the bottom of the object. No substantial changes
  • Added font JSON files
  • Fixed some particles after the upgrade to the latest Base UI (p-select-*.tsx)
  • Added agent skills

Agent Skills (apps/ui/skills/coss/)

  • 45 primitive skills in primitives/*/SKILL.md — each with unique trigger-optimized descriptions, compatibility field, metadata block (author/version), and spec-compliant name↔directory naming
  • "When NOT to use" sections on 19 confusable primitives (e.g. Dialog vs Sheet vs AlertDialog, Select vs Combobox vs Autocomplete)
  • 4 rule skills converted from plain .md to proper skill directories with SKILL.md frontmatter: styling, forms, composition, migration
  • Migration skill split: base-vs-radix.md → concise migration/SKILL.md + references/component-index.md (30-component index loaded on demand)
  • Component registry index (references/component-registry.md) for fast agent-driven primitive discovery
  • Root SKILL.md updated with compatibility, metadata, new paths, and component discovery workflow
  • cli.md moved to references/ directory

Migration Guide & Docs

  • Corrected Select prop mapping table (placeholder, alignItemWithTrigger)
  • Updated Select particles to use <SelectValue placeholder="..." /> instead of null-value items
  • Added DialogCreateHandle and DrawerCreateHandle docs
  • Added "Verify After Migration" checklist section
  • Clarified asChildrender pattern scope

Review & Testing Checklist for Human

  • Select particles visual check: p-select-1 through p-select-11 — verify placeholder text renders correctly now that null-value items are removed (behavioral change). This is the highest-risk change since it modifies runtime behavior.
  • Migration guide accuracy: Verify the corrected Select prop mapping table matches actual coss/Base UI API behavior (especially placeholder on SelectValue and alignItemWithTrigger on SelectPopup)
  • Skill path references: Spot-check that SKILL.md cross-references resolve correctly (e.g. root → primitives/dialog/SKILL.md, migration → references/component-index.md)
  • "When NOT to use" accuracy: Review disambiguation guidance on a few confusable primitives (e.g. Dialog/Sheet/Drawer, Select/Combobox) for correctness — these were written based on general UI patterns, not validated against coss-specific behavior

Recommended test plan: Run the dev server, navigate to the Select component particles page, and confirm all Select examples display properly with placeholder text instead of a selectable null-value option.

Notes

  • All skill files follow the agentskills.io specification format with YAML frontmatter
  • The Select particle changes are the only functional code changes; all other changes are documentation/skill content
  • Directory names use simple unprefixed names (dialog/, select/, styling/) since they already live under apps/ui/skills/coss/

Link to Devin session: https://app.devin.ai/sessions/d69512ae40264e9287a699d91a24f4ba
Requested by: @pasqualevitiello

@vercel
Copy link
Copy Markdown

vercel bot commented Mar 22, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
coss-com Ready Ready Preview, Comment Mar 22, 2026 10:54pm
coss-com-ui Ready Ready Preview, Comment Mar 22, 2026 10:54pm
coss-examples-calcom Ready Ready Preview, Comment Mar 22, 2026 10:54pm
1 Skipped Deployment
Project Deployment Actions Updated (UTC)
coss-com-origin Skipped Skipped Mar 22, 2026 10:54pm

Request Review

- Rename all 45 primitive dirs to match name fields (e.g. dialog/ -> coss-dialog/)
- Write unique, trigger-optimized descriptions for all primitives
- Replace user-invocable with compatibility field and metadata block
- Add 'When NOT to use' sections to 19 confusable primitives
- Convert rule files to proper skill dirs with SKILL.md frontmatter
- Split base-vs-radix.md into concise skill + references/component-index.md
- Add component registry index reference (references/component-registry.md)
- Move cli.md to references/ directory
- Update root SKILL.md with updated paths, component discovery section, metadata

Co-Authored-By: pasquale <pasqualevitiello@gmail.com>
The skills already live under apps/ui/skills/coss/, so the coss- prefix
on each directory/name was redundant. Reverts to simple names like
dialog/, select/, styling/, migration/, etc.

Co-Authored-By: pasquale <pasqualevitiello@gmail.com>
@sean-brydon sean-brydon merged commit 320871c into main Mar 23, 2026
14 checks passed
@sean-brydon sean-brydon deleted the pasquale/cui-154-agent-skills branch March 23, 2026 08:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants