Skills

The Sona UI skill helps coding agents choose, install, and validate components with context. It directs the agent to the registry and focused resources instead of copying component source into a prompt.

Install

Initialize shadcn if the project does not already include a components configuration file.

bunx shadcn@latest init

Add the Sona UI registry to the components configuration file.

{
"registries": {
  "@sona-ui": "https://sonaui.com/r/{name}.json"
}
}

Install the skill into the shared agent-skills directory.

bunx shadcn@latest add @sona-ui/agent-skill

What the skill provides

• Component selection based on intent and interaction requirements.
• Consumer-project inspection before an agent edits files.
• Registry-first installation and dependency checks.
• Accessibility and reduced-motion expectations.
• Sona UI motion and semantic-token guidance.
• Clear validation results and failure classification.

Use the skill

Ask an agent to consider the interaction first, then explain its choice before installation.

Find a Sona UI component for switching between related settings.
Explain the selection, accessibility behavior, reduced-motion behavior, and dependencies before installing anything.

The agent should inspect the consumer project and the Sona catalog, recommend a component, explain the trade-offs, and wait because the request explicitly says not to install.

Validate an installation

After installation, the agent should record a pass, failure, or not-run result for each relevant check.

1. Confirm registry dependencies and foundation files resolve.
2. Run the consumer typecheck or build command.
3. Exercise the primary keyboard interaction.
4. Check narrow and wide layouts.
5. Check light and dark themes when supported.
6. Check reduced-motion behavior.

Static checks confirm source health, but they do not prove interaction or visual quality.

Client support

The skill uses the open SKILL.md package structure. Discovery of the shared agent-skills directory depends on the coding client and its configuration. Codex, Claude Code, and Cursor each have configuration fixtures in this repository.

Troubleshooting

When installation fails, identify the boundary before changing source. The issue may be consumer configuration, registry metadata, generated payloads, agent resources, client configuration, or deployment availability.

If a client does not detect the skill, confirm that it was installed to the directory expected by that client, then restart or reload the client.

Contact

Found a bug or need help using this skill? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this skill in personal and commercial projects.