# Sistema de Skills do AIOSON

O AIOSON possui um sistema de skills que fornece convenções, padrões e referências específicas por framework, design system ou domínio técnico. As skills são carregadas sob demanda pelos agentes conforme o contexto do projeto.

## Tipos de skills

### Skills gerenciadas (`.aioson/skills/`)

Distribuídas automaticamente pelo CLI durante `aioson init` ou `aioson update`. São **gitignored** — não versionadas com o projeto, pois o CLI as mantém atualizadas.

Estrutura:

```
.aioson/skills/
├── static/          ← convenções e padrões por framework
│   ├── laravel-conventions.md
│   ├── tall-stack-patterns.md
│   ├── jetstream-setup.md
│   ├── filament-patterns.md
│   ├── flux-ui-components.md
│   ├── django-patterns.md
│   ├── fastapi-patterns.md
│   ├── rails-conventions.md
│   ├── nextjs-patterns.md
│   ├── react-motion-patterns.md
│   ├── node-express-patterns.md
│   ├── node-typescript-patterns.md
│   ├── web3-ethereum-patterns.md
│   ├── web3-solana-patterns.md
│   ├── web3-cardano-patterns.md
│   └── web3-security-checklist.md
├── dynamic/         ← referências consultadas via web quando necessário
│   ├── laravel-docs.md
│   ├── flux-ui-docs.md
│   ├── npm-packages.md
│   ├── ethereum-docs.md
│   ├── solana-docs.md
│   └── cardano-docs.md
├── design/          ← design systems visuais
│   ├── cognitive-core-ui/
│   ├── interface-design/
│   └── premium-command-center-ui/
└── process/         ← metodologia de fluxo e contratos entre agentes
    └── aioson-spec-driven/
```

**Carregamento condicional:** O agente `@dev` carrega apenas as skills que correspondem ao valor de `framework` em `project.context.md`. Exemplo: se `framework=Laravel`, carrega `laravel-conventions.md` e opcionalmente `tall-stack-patterns.md` se o stack for TALL.

**Process skills** são carregadas pelos agentes de spec (`@product`, `@analyst`, `@architect`, `@sheldon`, `@dev`, `@deyvin`) no início de sessões de especificação, requirements e design — nunca todas de uma vez. Cada agente carrega o `SKILL.md` central e depois apenas o arquivo de `references/` relevante para sua fase atual.

### Skills instaladas (`.aioson/installed-skills/`)

Skills versionadas com o projeto. Entram aqui em dois casos:

- skills de terceiros instaladas pelo usuário via CLI
- skills locais geradas dentro do próprio projeto por agentes/process skills

Cada skill instalada contém um `SKILL.md` com frontmatter YAML descrevendo quando usá-la.
Quando existir, o arquivo `.skill-meta.json` registra origem, autor e metadados do gerador/modelo.

## Instalando skills

### Via npm (pacotes públicos)

```bash
aioson skill:install @tech-leads-club/agent-skills --skill coupling-analysis
```

Isso:
1. Baixa o pacote npm temporariamente
2. Copia a skill para `.aioson/installed-skills/{nome}/`
3. Distribui recursivamente para ferramentas nativas (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`)
4. Registra a skill na seção "Installed skills" do `AGENTS.md`

### Via aioson.com (registry cloud)

```bash
aioson skill:install cloud:nome-da-skill
```

Requer autenticação com `aioson auth:login`. Busca skills publicadas no marketplace do aioson.com.

### Via arquivo local

```bash
aioson skill:install ./caminho/para/skill/
```

Copia o diretório da skill diretamente para `.aioson/installed-skills/`.

## Gerenciando skills

### Listar skills instaladas

```bash
aioson skill:list
```

Mostra todas as skills em `.aioson/installed-skills/` com nome, descrição e fonte.
Quando a metadata existir, também pode mostrar autor e modelo gerador.

### Remover uma skill

```bash
aioson skill:remove nome-da-skill
```

Remove de `.aioson/installed-skills/` e de todos os diretórios de ferramentas (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`).

## Compatibilidade com ferramentas

As skills instaladas são distribuídas automaticamente para as ferramentas de IA suportadas:

| Ferramenta | Diretório | Como acessa |
|------------|-----------|-------------|
| Claude Code | `.claude/skills/` | Acesso direto por path |
| Cursor | `.cursor/skills/` | Acesso direto por path |
| Windsurf | `.windsurf/skills/` | Acesso direto por path |
| Codex | `AGENTS.md` | Via referência `@slug` no arquivo AGENTS.md |

### Nota sobre gitignore

Mesmo que `.aioson/skills/` esteja no gitignore, todas as ferramentas (Claude Code, Codex) conseguem ler os arquivos via path direto no filesystem. O gitignore afeta apenas a descoberta automática do Codex via `@` — mas como as skills são referenciadas por path explícito nos agentes, isso não é um problema.

## Mapeamento framework → skill

O agente `@dev` usa o valor de `framework` do `project.context.md` para decidir quais skills carregar:

| Framework | Skill estática | Referência dinâmica |
|-----------|---------------|---------------------|
| Laravel | `laravel-conventions.md` | `laravel-docs.md` |
| Laravel + TALL | + `tall-stack-patterns.md` | |
| Laravel + Jetstream | + `jetstream-setup.md` | |
| Laravel + Filament | + `filament-patterns.md` | |
| Laravel + Flux UI | + `flux-ui-components.md` | `flux-ui-docs.md` |
| Django | `django-patterns.md` | |
| FastAPI | `fastapi-patterns.md` | |
| Rails | `rails-conventions.md` | |
| Next.js | `nextjs-patterns.md` | `npm-packages.md` |
| React | `react-motion-patterns.md` | `npm-packages.md` |
| Express / Fastify | `node-express-patterns.md` | `npm-packages.md` |
| Node.js + TypeScript | `node-typescript-patterns.md` | `npm-packages.md` |

Para projetos Web3, skills adicionais são carregadas conforme `web3_networks`:

| Rede | Skill estática | Referência dinâmica |
|------|---------------|---------------------|
| Ethereum | `web3-ethereum-patterns.md` | `ethereum-docs.md` |
| Solana | `web3-solana-patterns.md` | `solana-docs.md` |
| Cardano | `web3-cardano-patterns.md` | `cardano-docs.md` |

## Skills de design

Skills de design são especiais — apenas **uma** pode estar ativa por projeto, definida pelo campo `design_skill` em `project.context.md`. O agente `@dev` aplica exclusivamente o design system selecionado, sem misturar padrões de outros sistemas.

Skills de design disponíveis (as mesmas oferecidas pelo wizard do `init`/`install`):

| Skill | Para |
|---|---|
| `clean-saas-ui` | Mínima e funcional — dashboards e ferramentas |
| `aurora-command-ui` | Escura e luminosa — command centers e apps |
| `cognitive-core-ui` | Densa em informação — dados e analytics |
| `bold-editorial-ui` | Tipografia de alto contraste — sites de conteúdo |
| `warm-craft-ui` | Tons quentes e orgânicos — consumo e lifestyle |
| `glassmorphism-ui` | Camadas translúcidas — interfaces imersivas |
| `neo-brutalist-ui` | Cru e de alto contraste — declarações fortes |
| `premium-command-center-ui` | Nível enterprise — operação e monitoramento |
| `interface-design` | Sistema fundacional, de propósito geral |

A skill `interface-design` é um **motor**: antes de desenhar, ela resolve a autoridade visual em ordem, parando no primeiro acerto — (1) um protótipo aprovado vinculado pelo PRD (`prototype_status: current`), em **modo conformidade**; (2) o registro `identity.md` que o PRD vincula via `identity`/`identity_status`; (3) `.aioson/explorations/{slug}/identity.md` (só em modo exploração, nunca para trabalho canônico); (4) `.aioson/briefings/{slug}/identity.md`; (5) `.aioson/context/identity.md`; (6) a linguagem de componentes já estabelecida no repositório; (7) nenhuma — **modo origem**. Sem nenhum sinal, roda intent-first.

Em **modo conformidade**, a skill não decide direção de novo — ela transfere a direção já aprovada: lê o protótipo e sua `## Visual direction`, extrai os tokens e a anatomia de componentes reais já expressos ali, e mapeia cada região para o componente correspondente na biblioteca do projeto. Um desvio só é válido se já estiver registrado no PRD como desvio aprovado.

O `identity.md` é extraído **uma única vez** das suas imagens de referência pela skill de processo `reference-identity-extract`, e todo consumidor do motor (`@dev`, `@deyvin`, `@ux-ui`, protótipos) herda essa resolução — ele é *input* paramétrico do motor, não um segundo design skill. O arquivo legado `.interface-design/system.md` (memória de design por projeto) foi superado pelo registro de identidade sob `.aioson/`: duas camadas de continuidade visual eram livres para divergir.

### Quando `design_skill` está em branco

O `@briefing-refiner` não pergunta e não escolhe no escuro: ele adota `interface-design` em modo origem. Mas o padrão é **declarado, nunca silencioso** — ele grava `design_skill: interface-design (default)` no `prototype-manifest.md` e registra um achado estruturado não-bloqueante recomendando que o projeto defina um `design_skill` definitivo.

Se o `design_skill` nomeia um preset instalado, só aquele preset é usado. Imagens de referência continuam opcionais; quando você fornece, a rota de identidade acima vale.

### Registro estético e direção — a partida a frio

Em modo origem (nenhum protótipo, nenhum `identity.md`, nenhuma linguagem de componentes estabelecida), a `interface-design` se compromete com **um registro** antes de decidir qualquer token. É o momento exato em que um sistema generativo volta para a média estatística, porque "clean modern SaaS" é a cara da média.

Duas escolhas, feitas juntas:

- **Direção** (`design-directions.md`) responde o que o produto **precisa**: Precision & Density, Warmth & Approachability, Sophistication & Trust, Premium Dark Platform, Immersive Media, Conversion Landing. Ela define a matemática dos tokens.
- **Registro** (`aesthetic-registers.md`) responde como o produto **soa**: Technical, Quiet, Editorial, Material, Constructed, Cinematic. Ele define a postura.

Nunca se mistura dois registros. As famílias tipográficas citadas em cada registro são exemplos de uma classe, não padrões para aceitar sem examinar.

Duas adições recentes:

- **Registro Cinematic** — para entretenimento, streaming, cinema, jogos, portfólios imersivos: fundo quase preto, paleta amostrada da própria mídia, frames full-bleed em vez de linhas de grade, luz no lugar de bordas, motion coreografado que degrada para frames estáticos com sentido sob `prefers-reduced-motion`. O modo de falha é "um trailer com botões".
- **Direções Immersive Media e Conversion Landing** — a primeira combina naturalmente com o registro Cinematic; a segunda é para superfícies cujo trabalho é **uma** decisão: um único acento de conversão reservado ao CTA principal, ordem narrativa promessa → prova → capacidade → objeção → CTA, e prova real com fonte, nunca métrica inventada.

O registro escolhido, os anti-objetivos e o movimento-assinatura vão para a seção `## Visual direction` do manifesto do protótipo e, quando a decisão vale para o projeto inteiro, para o registro de identidade. Registro escolhido e não escrito é registro re-decidido pelo próximo agente.

## Skills de processo

Skills de processo ensinam os agentes **como as fases do AIOSON se conectam** — não o que implementar, mas como sequenciar, quando aprofundar e como fazer handoff limpo entre agentes.

Diferente das skills de framework (que são por stack) e das skills de design (que são por sistema visual), process skills são transversais: carregadas por qualquer agente de spec conforme a fase em que ele se encontra.

### `aioson-spec-driven`

Localização: `.aioson/skills/process/aioson-spec-driven/`

A skill central de metodologia do AIOSON. Cobre:

- **Sequência de fases** — quais fases existem, quais artefatos cada uma produz e quem é o agente responsável
- **Profundidade por classificação** — MICRO usa fluxo mínimo, SMALL usa fluxo padrão, MEDIUM usa pacote completo
- **Gates de aprovação** — Gate A (requirements), Gate B (design), Gate C (plan) — critérios do que deve estar pronto antes de avançar para a próxima fase
- **Hardening lane** — como identificar quando um input ainda está em modo "exploratório/vibe" e o que fazer para convertê-lo em spec executável
- **Manutenção e estado** — como escrever checkpoints úteis em `spec-{slug}.md` para que qualquer agente ou sessão futura possa retomar sem redescobrir o que já foi decidido

**Estrutura:**

```
.aioson/skills/process/aioson-spec-driven/
├── SKILL.md                          ← entry point curto — carregue sempre primeiro
└── references/
    ├── artifact-map.md               ← qual artefato fica onde e quem é o dono
    ├── classification-map.md         ← profundidade de fase por MICRO/SMALL/MEDIUM
    ├── approval-gates.md             ← critérios dos Gates A, B e C
    ├── hardening-lane.md             ← quando endurecer vs quando explorar
    └── maintenance-and-state.md      ← como escrever spec e checkpoints úteis
```

**Carregamento:** Os agentes `@product`, `@analyst`, `@architect`, `@sheldon`, `@dev` e `@deyvin` verificam automaticamente se esta skill está disponível e carregam `SKILL.md` + apenas o arquivo de `references/` relevante para a fase atual. Nunca carregam a pasta inteira de uma vez.

### `design-hybrid-forge`

Localização: `.aioson/skills/process/design-hybrid-forge/`

Skill first-party para criar uma nova skill de design híbrida a partir de **2 skills primárias obrigatórias** e, opcionalmente, até 2 modificadores de escopo limitado. Em modo avançado, pode liberar um 3º modificador, ainda preso a lanes secundárias.

Se você quer o fluxo completo em um só lugar, leia a página dedicada: [design-hybrid-forge](../4-agentes/design-hybrid-forge.md).

Fluxo padrão:

1. O usuário ativa `@design-hybrid-forge` no Codex ou `/aioson:agent:design-hybrid-forge` no Claude
2. Se quiser um overlay visual mais ousado, o usuário pode rodar `aioson design-hybrid:options` para gerar `.aioson/context/design-variation-preset.md`
3. O comando usa `conversation_language` do projeto quando existir; `--locale` funciona como override manual
4. O agente pede as 2 skills primárias, até 2 modificadores opcionais e lê o preset visual quando ele existir
5. Se o usuário tiver criado o preset com `--advanced`, o agente pode aceitar um 3º modificador de escopo estreito
6. O híbrido é gerado em `.aioson/installed-skills/{slug}/`
7. O `AGENTS.md` é atualizado para que o Codex possa usar `@{slug}`
8. O pacote também pode ser espelhado para `.claude/skills/`, `.cursor/skills/` e `.windsurf/skills/`

Saída padrão:

```
.aioson/installed-skills/{slug}/
  SKILL.md
  .skill-meta.json
  references/
  previews/
```

Esse fluxo cria uma **skill local do projeto**. Se depois você quiser promover a skill para o core do AIOSON ou para um marketplace, trate isso como uma segunda etapa de curadoria, separada da geração local.

O preset criado em `.aioson/context/design-variation-preset.md` é **temporário**:
- ele serve como input para a próxima geração híbrida
- depois da geração, deve ser removido ou movido do contexto ativo
- uma cópia histórica fica em `.aioson/context/history/design-variation-presets/`
- ele não redefine o layout padrão do projeto; quem continua mandando no projeto é a `design_skill` ativa

O preset gerado por `design-hybrid:options` cobre direções como:
- clássico / editorial
- extravagante / maximalista
- cinematográfico / imersivo
- retrofuturista
- motion-driven
- CSS avançado (scroll-driven animations, View Transition API, masks, SVG filters, 3D)

Recomendação de uso:
- fluxo normal: até 2 modificadores
- fluxo avançado: `aioson design-hybrid:options --advanced` para permitir até 3 modificadores
- mesmo no modo avançado, modificadores não podem dominar substrato nem estrutura

## Skills de squad

Squads podem ter suas próprias skills em `.aioson/squads/{squad-slug}/skills/`. Essas são carregadas automaticamente quando a tarefa pertence ao escopo do squad.

## Criando skills

Uma skill é um diretório com pelo menos um arquivo `SKILL.md` contendo:

```markdown
---
name: nome-da-skill
description: Descrição curta do que a skill faz
triggers:
  - quando usar esta skill
  - outro cenário de uso
---

# Nome da Skill

Conteúdo da skill com convenções, padrões, exemplos de código, etc.
```

O frontmatter `description` e `triggers` são usados pelos agentes para decidir se devem carregar a skill para a tarefa atual.

---

## Veja também

- [Comandos CLI](./comandos-cli.md) — `skill:install`, `skill:list`, `skill:remove`, `skill:publish`
- [Design Hybrid Forge](../4-agentes/design-hybrid-forge.md) — criar híbridos de design skills
- [SDD Framework](./sdd-framework.md) — o skill `aioson-spec-driven` que governa o processo