Geruyang/agent-skills-library

Exportar cópia de limites e aliases de skill

Migração, instalação, correção e escrita de experiência atuam apenas na cópia da skill hospedeira atualmente carregada. O Codex original skill/MCP, o código fonte baixado e original-skills são materiais de origem; não são gravados pela execução desta cópia. Apenas quando o usuário solicitar explicitamente a configuração do produto Codex em si, o fluxo desse produto será usado para processar o destino especificado. Quando um script precisar de um diretório de instalação ou diretório de estado, forneça explicitamente o caminho de destino; não inferir implicitamente o local de gravação a partir de CODEX_HOME.

Nomes entre skills podem herdar aliases do repositório de origem. Primeiro consulte a tabela de aliases de skill, priorize itens da mesma fonte e mesmo plugin e, em seguida, use seu id para chamar ou ler a entrada correspondente; não assuma que nomes antigos $skill ou superpowers:skill estejam registrados diretamente no novo host. Quando não for possível determinar o destino, verifique primeiro; não substitua comandos reais do produto ou variáveis de ambiente do Shell.

Convenções de uso entre hosts

Esta cópia é para uso em clientes compatíveis com Agent Skills. Verifique primeiro as ferramentas, permissões e serviços conectados realmente fornecidos pelo host atual antes de executar o fluxo de trabalho do corpo do texto. Os identificadores de ferramentas do host no texto original são referências de capacidade; você só pode chamar a ferramenta se ela realmente existir. Outros hosts devem usar o MCP, CLI ou API equivalente e verificado. Etapas sem capacidade equivalente devem ser relatadas como indisponíveis; não invente chamadas ou estados de conclusão.

Os recursos da skill são baseados no diretório da skill; a saída é gravada no local especificado pelo usuário no projeto atual. A skill pode ser acionada por nome ou linguagem natural; os comandos curtos específicos são definidos pelo host. Nomes envolvendo produtos reais, APIs de modelo, campos de protocolo e URLs oficiais devem ser mantidos no original. Autorização, aprovação, privacidade e limites de escopo da ferramenta permanecem válidos após a migração; não expanda permissões para compatibilidade. Consulte PORTABILITY.md no mesmo diretório para dependências específicas e instruções de migração.

shadcn/ui

Um framework para construir UI, componentes e sistemas de design. Os componentes são adicionados como código fonte ao projeto do usuário via CLI.

IMPORTANTE: Execute todos os comandos da CLI usando o executor de pacotes do projeto: npx shadcn@latest, pnpm dlx shadcn@latest ou bunx --bun shadcn@latest — com base no packageManager do projeto. Os exemplos abaixo usam npx shadcn@latest, mas substitua pelo executor correto para o projeto.

Contexto Atual do Projeto

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "Nenhum projeto shadcn encontrado. Execute shadcn init primeiro."}'`

O JSON acima contém a configuração do projeto e os componentes instalados. Use npx shadcn@latest docs <component> para obter URLs de documentação e exemplos para qualquer componente.

Princípios

1. Use componentes existentes primeiro. Use npx shadcn@latest search para verificar registros antes de escrever UI personalizada. Verifique também registros da comunidade.
2. Componha, não reinvente. Página de configurações = Tabs + Card + controles de formulário. Painel de controle = Sidebar + Card + Chart + Table.
3. Use variantes integradas antes de estilos personalizados. variant="outline", size="sm", etc.
4. Use cores semânticas. bg-primary, text-muted-foreground — nunca valores brutos como bg-blue-500.

Regras Críticas

Estas regras são sempre aplicadas. Cada uma tem um link para um arquivo com pares de código Incorreto/Correto.

Estilização e Tailwind → styling.md

• className para layout, não para estilização. Nunca substitua cores ou tipografia de componentes.
• Sem space-x-* ou space-y-*. Use flex com gap-*. Para pilhas verticais, flex flex-col gap-*.
• Use size-* quando largura e altura forem iguais. size-10 em vez de w-10 h-10.
• Use a abreviação truncate. Não overflow-hidden text-ellipsis whitespace-nowrap.
• Sem substituições manuais de cor dark:. Use tokens semânticos (bg-background, text-muted-foreground).
• Use cn() para classes condicionais. Não escreva ternários manuais de template literal.
• Sem z-index manual em componentes de sobreposição. Dialog, Sheet, Popover etc. gerenciam seu próprio empilhamento.

Formulários e Inputs → forms.md

• Formulários usam FieldGroup + Field. Nunca use div bruto com space-y-* ou grid gap-* para layout de formulário.
• InputGroup usa InputGroupInput/InputGroupTextarea. Nunca Input/Textarea bruto dentro de InputGroup.
• Botões dentro de inputs usam InputGroup + InputGroupAddon.
• Conjuntos de opções (2–7 escolhas) usam ToggleGroup. Não faça loop de Button com estado ativo manual.
• FieldSet + FieldLegend para agrupar checkboxes/radios relacionados. Não use um div com título.
• Validação de campo usa data-invalid + aria-invalid. data-invalid no Field, aria-invalid no controle. Para desabilitado: data-disabled no Field, disabled no controle.

Estrutura de Componentes → composition.md

• Itens sempre dentro de seus Grupos. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
• Use asChild (radix) ou render (base) para gatilhos personalizados. Verifique o campo base de npx shadcn@latest info. → base-vs-radix.md
• Dialog, Sheet e Drawer sempre precisam de um Title. DialogTitle, SheetTitle, DrawerTitle são obrigatórios para acessibilidade. Use className="sr-only" se estiver oculto visualmente.
• Use a composição completa do Card. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Não coloque tudo em CardContent.
• Button não tem isPending/isLoading. Componha com Spinner + data-icon + disabled.
• TabsTrigger deve estar dentro de TabsList. Nunca renderize gatilhos diretamente em Tabs.
• Avatar sempre precisa de AvatarFallback. Para quando a imagem não carregar.

Use Componentes, Não Marcação Personalizada → composition.md

• Use componentes existentes antes de marcação personalizada. Verifique se um componente existe antes de escrever um div estilizado.
• Callouts usam Alert. Não construa divs estilizados personalizados.
• Estados vazios usam Empty. Não construa marcação de estado vazio personalizada.
• Toast via sonner. Use toast() de sonner.
• Use Separator em vez de <hr> ou <div className="border-t">.
• Use Skeleton para placeholders de carregamento. Sem divs personalizados com animate-pulse.
• Use Badge em vez de spans estilizados personalizados.

Ícones → icons.md

• Ícones em Button usam data-icon. data-icon="inline-start" ou data-icon="inline-end" no ícone.
• Sem classes de tamanho em ícones dentro de componentes. Os componentes gerenciam o tamanho dos ícones via CSS. Sem size-4 ou w-4 h-4.
• Passe ícones como objetos, não como chaves de string. icon={CheckIcon}, não uma busca por string.

CLI

• Nunca decodifique ou busque códigos de preset manualmente. Passe-os diretamente para npx shadcn@latest init --preset <code>.

Padrões Principais

Estes são os padrões mais comuns que diferenciam o código shadcn/ui correto. Para casos extremos, consulte os arquivos de regras vinculados acima.

// Layout de formulário: FieldGroup + Field, não div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// Validação: data-invalid no Field, aria-invalid no controle.
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>Email inválido.</FieldDescription>
</Field>

// Ícones em botões: data-icon, sem classes de tamanho.
<Button>
  <SearchIcon data-icon="inline-start" />
  Pesquisar
</Button>

// Espaçamento: gap-*, não space-y-*.
<div className="flex flex-col gap-4">  // correto
<div className="space-y-4">           // errado

// Dimensões iguais: size-*, não w-* h-*.
<Avatar className="size-10">   // correto
<Avatar className="w-10 h-10"> // errado

// Cores de status: variantes de Badge ou tokens semânticos, não cores brutas.
<Badge variant="secondary">+20.1%</Badge>    // correto
<span className="text-emerald-600">+20.1%</span> // errado

Seleção de Componentes

Necessidade	Use
Botão/ação	Button com variante apropriada
Inputs de formulário	Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider
Alternar entre 2–5 opções	ToggleGroup + ToggleGroupItem
Exibição de dados	Table, Card, Badge, Avatar
Navegação	Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination
Sobreposições	Dialog (modal), Sheet (painel lateral), Drawer (inferior), AlertDialog (confirmação)
Feedback	sonner (toast), Alert, Progress, Skeleton, Spinner
Paleta de comandos	Command dentro de Dialog
Gráficos	Chart (encapsula Recharts)
Layout	Card, Separator, Resizable, ScrollArea, Accordion, Collapsible
Estados vazios	Empty
Menus	DropdownMenu, ContextMenu, Menubar
Dicas/informações	Tooltip, HoverCard, Popover

Campos Principais

O contexto do projeto injetado contém estes campos principais:

• aliases → use o prefixo de alias real para imports (ex: @/, ~/), nunca hardcode.
• isRSC → quando true, componentes que usam useState, useEffect, manipuladores de evento ou APIs do navegador precisam de "use client" no topo do arquivo. Sempre consulte este campo ao aconselhar sobre a diretiva.
• tailwindVersion → "v4" usa blocos @theme inline; "v3" usa tailwind.config.js.
• tailwindCssFile → o arquivo CSS global onde as variáveis CSS personalizadas são definidas. Sempre edite este arquivo, nunca crie um novo.
• style → tratamento visual do componente (ex: nova, vega).
• base → biblioteca primitiva (radix ou base). Afeta as APIs do componente e as props disponíveis.
• iconLibrary → determina os imports de ícone. Use lucide-react para lucide, @tabler/icons-react para tabler, etc. Nunca assuma lucide-react.
• resolvedPaths → destinos exatos no sistema de arquivos para componentes, utils, hooks, etc.
• framework → roteamento e convenções de arquivo (ex: Next.js App Router vs Vite SPA).
• packageManager → use este para qualquer instalação de dependência que não seja shadcn (ex: pnpm add date-fns vs npm install date-fns).

Consulte cli.md — comando info para a referência completa dos campos.

Documentação, Exemplos e Uso de Componentes

Execute npx shadcn@latest docs <component> para obter as URLs para a documentação, exemplos e referência de API de um componente. Busque essas URLs para obter o conteúdo real.

npx shadcn@latest docs button dialog select

Ao criar, corrigir, depurar ou usar um componente, sempre execute npx shadcn@latest docs e busque as URLs primeiro. Isso garante que você esteja trabalhando com a API e os padrões de uso corretos, em vez de adivinhar.

Fluxo de Trabalho

1. Obter contexto do projeto — já injetado acima. Execute npx shadcn@latest info novamente se precisar atualizar.
2. Verificar componentes instalados primeiro — antes de executar add, sempre verifique a lista de components do contexto do projeto ou liste o diretório resolvedPaths.ui. Não importe componentes que não foram adicionados e não readicione os já instalados.
3. Encontrar componentes — npx shadcn@latest search.
4. Obter documentação e exemplos — execute npx shadcn@latest docs <component> para obter URLs e, em seguida, busque-os. Use npx shadcn@latest view para navegar por itens do registro que você não instalou. Para visualizar alterações em componentes instalados, use npx shadcn@latest add --diff.
5. Instalar ou atualizar — npx shadcn@latest add. Ao atualizar componentes existentes, use --dry-run e --diff para visualizar as alterações primeiro (consulte Atualizando Componentes abaixo).
6. Corrigir imports em componentes de terceiros — Após adicionar componentes de registros da comunidade (ex: @bundui, @magicui), verifique os arquivos não-UI adicionados em busca de caminhos de import hardcoded como @/components/ui/.... Eles podem não corresponder aos aliases reais do projeto. Use npx shadcn@latest info para obter o alias ui correto (ex: @workspace/ui/components) e reescreva os imports de acordo. A CLI reescreve imports para seus próprios arquivos UI, mas componentes de registro de terceiros podem usar caminhos padrão que não correspondem ao projeto.
7. Revisar componentes adicionados — Após adicionar um componente ou bloco de qualquer registro, sempre leia os arquivos adicionados e verifique se estão corretos. Verifique se há subcomponentes ausentes (ex: SelectItem sem SelectGroup), imports ausentes, composição incorreta ou violações das Regras Críticas. Substitua também quaisquer imports de ícone pela iconLibrary do projeto no contexto do projeto (ex: se o item do registro usa lucide-react mas o projeto usa hugeicons, troque os imports e nomes de ícone de acordo). Corrija todos os problemas antes de prosseguir.
8. O registro deve ser explícito — Quando o usuário pedir para adicionar um bloco ou componente, não adivinhe o registro. Se nenhum registro for especificado (ex: o usuário diz "adicione um bloco de login" sem especificar @shadcn, @tailark, etc.), pergunte qual registro usar. Nunca escolha um registro padrão em nome do usuário.
9. Alternar presets — Pergunte ao usuário primeiro: reinstalar, mesclar ou pular?
   • Reinstalar: npx shadcn@latest init --preset <code> --force --reinstall. Sobrescreve todos os componentes.
   • Mesclar: npx shadcn@latest init --preset <code> --force --no-reinstall, depois execute npx shadcn@latest info para listar os componentes instalados e, em seguida, para cada componente instalado, use --dry-run e --diff para mesclá-lo inteligentemente individualmente.
   • Pular: npx shadcn@latest init --preset <code> --force --no-reinstall. Apenas atualiza a configuração e o CSS, deixando os componentes como estão.
   • Importante: Sempre execute comandos de preset dentro do diretório do projeto do usuário. A CLI preserva automaticamente a base atual (base vs radix) de components.json. Se você precisar usar um diretório temporário/scratch (ex: para comparações --dry-run), passe --base <base-atual> explicitamente — códigos de preset não codificam a base.

Atualizando Componentes

Quando o usuário pedir para atualizar um componente a partir do upstream mantendo suas alterações locais, use --dry-run e --diff para fazer merge de forma inteligente. NUNCA busque arquivos brutos diretamente do registro. O CLI é a única interface suportada.

1. Identifique o componente a ser atualizado.
2. Execute npx shadcn@latest add <componente> --dry-run --diff para ver as alterações propostas.
3. Analise as diferenças. Mantenha as alterações locais que não conflitam com o upstream.
4. Execute npx shadcn@latest add <componente> --overwrite para aplicar as alterações.
5. Execute git diff no diretório do arquivo para ver o resultado final.

Exemplo de Paleta de Comandos

Crie uma paleta de comandos pesquisável com Command dentro de Dialog:

import {
  Command,
  CommandDialog,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command"

Resolução de Problemas

Quando um componente não estiver se comportando como esperado:

1. Execute npx shadcn@latest docs <componente> e busque as URLs para confirmar o uso correto.
2. Verifique se o componente está instalado: procure por ele no diretório resolvedPaths.ui.
3. Verifique se todos os subcomponentes necessários estão instalados e importados.
4. Verifique se as regras de composição estão sendo seguidas (ex: itens dentro de grupos).
5. Verifique se as variantes e props estão corretas.
6. Verifique se o alias de import corresponde ao aliases do projeto.

Para problemas com o CLI, execute npx shadcn@latest --help ou npx shadcn@latest <comando> --help.