Skill para IA
Um guia em Markdown para assistentes (Cursor, Claude Code, Claude na web, etc.): qual componente @youxgroup usar e como compor telas no seu app — independente do editor.
Para quem é
Desenvolvedores que já instalaram (ou vão instalar) o Marsala DS no repositório do produto.
- Escolher entre
dialog,drawer,toast,sidebar, etc. - Montar formulários com
fielde features emcomponents/<feature>, sem duplicarcomponents/ui. - Aplicar tokens (
primary,muted, status semânticos) de forma consistente. - Refatorar telas legadas (hex, MUI, outro DS) com o guia
refatorar-design.mdno mesmo pacote.
O guia não substitui a documentação de cada componente — consulte o catálogo quando precisar de API e exemplos.
Skill vs MCP
Os dois ajudam a IA a usar o Marsala; o papel de cada um é diferente.
| Recurso | Skill (este guia) | MCP shadcn |
|---|---|---|
| O que faz | Regras e tabelas de decisão (qual componente, pastas, checklist) | Lista o registry, roda shadcn add no seu projeto |
| Funciona em | Qualquer agente que leia arquivos do repo ou instruções do projeto | Editores com MCP (Cursor, Claude Code, VS Code, etc.) |
| Use quando | Implementar UI e revisar coesão com o DS | Instalar e descobrir itens @youxgroup |
Recomendado: Instalação, skill + MCP no mesmo projeto.
1. Instale o guia (CLI)
Na raiz do seu app, com o namespace @youxgroup no components.json.
Mesmo fluxo dos componentes UI — veja Instalação.
{
"registries": {
"@youxgroup": "https://marsala-ds.youxgroup.com.br/r/{name}.json"
}
}pnpm dlx shadcn@latest add @youxgroup/marsala-skillO comando grava SKILL.md (produto novo) e refatorar-design.md (migração) em:
.cursor/skills/marsala-design-system/— Cursordocs/marsala-ds/— Claude e referência humana no repo
Alternativa sem shadcn CLI
Baixa o Markdown do site publicado.
curl -fsSL "https://marsala-ds.youxgroup.com.br/scripts/install-cursor-skill.mjs" -o /tmp/marsala-install-skill.mjs && node /tmp/marsala-install-skill.mjs && rm /tmp/marsala-install-skill.mjsRequer Node 18+ e acesso a https://marsala-ds.youxgroup.com.br.
2. Cursor
Skills em `.cursor/skills/` são carregadas pelo agente do Cursor.
Segue a skill marsala-design-system do projeto.
Preciso de uma tela de convite de usuário: qual componente Marsala usar
e um exemplo com Field, Input e Button.Nome da skill: marsala-design-system.
3. Claude Code e Claude (Anthropic)
Não há pasta `.cursor` obrigatória — use a cópia em `docs/`.
Claude Code (terminal/IDE): aponte o agente para o arquivo no repositório. Exemplo de trecho no CLAUDE.md na raiz:
# Marsala Design System
UI nova: siga `docs/marsala-ds/SKILL.md`.
Migrar design legado (cores/bibliotecas antigas): `docs/marsala-ds/refatorar-design.md`.
Use componentes @youxgroup; não duplique primitivos em components/ui.Claude (chat com projetos): em Configurações do projeto → conhecimento / arquivos, inclua docs/marsala-ds/SKILL.md (ou faça upload após o shadcn add).
Para instalar componentes com IA no Claude Code, configure o MCP shadcn — vale para Cursor e para outros clientes MCP.
4. Outros assistentes
Copilot, Windsurf, Gemini CLI, etc.
- Referencie
docs/marsala-ds/SKILL.mdnas instruções do projeto (ex.:.github/copilot-instructions.md,AGENTS.md, regras do editor). - Ou cole seções relevantes nas regras do time — o arquivo completo é a fonte de verdade no repo.
- Catálogo e exemplos continuam no site Marsala; a skill resume decisões, não substitui /componentes.
O que o guia cobre
Resumo — detalhes no SKILL.md instalado.
- Setup
@youxgroup/basee instalação por componente. - Estrutura de pastas no app (
components/uivs features). - Tabelas "qual componente usar" (feedback, formulário, overlay, shell, dados).
- Tokens e tema (resumo); migração detalhada em
refatorar-design.md. - Como estender UI sem fork; checklist antes de entregar a tela.