# Skills SDD e catálogo híbrido
Este documento descreve o contrato de skills da camada SDD. A fonte canônica do catálogo é `templates/skill-catalog.yaml`; os arquivos de skill continuam em Markdown (`SKILL.md`) e podem ser sincronizados para os clientes suportados pelo CLI.
## Visão geral
O catálogo é híbrido:
- skills SDD centrais continuam distribuídas pela camada e pelo plugin de orquestração;
- skills independentes e específicas de stack vivem em `.agents/skills/<id>/SKILL.md`;
- clients como Claude, Cursor, Devin, opencode, Trae e Antigravity podem receber cópias sincronizadas pelo CLI;
- recomendações por stack vindas de `sdd context recommend` precisam apontar para IDs existentes no catálogo ou para skills marcadas como `planned`.
O objetivo é permitir que uma skill seja acionada fora do contexto SDD quando o client suportar skill discovery, e também complementar etapas SDD quando o fluxo estiver em Project Discovery, Tech Spec, Execution, Review ou Memory.
## Comandos
```bash
sdd skills list
sdd skills list --json
sdd skills doctor --strict
sdd skills doctor --strict --json
sdd skills sync --targets codex,claude,cursor,devin,kiro,opencode,trae,antigravity --dry-run
sdd skills sync --targets codex,claude --force
sdd skills recommend --write
sdd skills validate .agents/skills/<skill>/SKILL.md --json
```
Use `--root <path>` quando estiver validando um projeto instalado fora do diretório atual.
## Catálogo
`templates/skill-catalog.yaml` usa `version: 1` e uma lista `skills`.
Campos por skill:
| Campo | Obrigatório | Uso |
| -------------------- | ----------: | --------------------------------------------------------------------------------------------------- |
| `id` | sim | Identificador estável usado por recomendações, sync e validação. |
| `title` | sim | Nome legível para listagens e relatórios. |
| `description` | sim | Resumo operacional da skill. |
| `category` | sim | Agrupamento para navegação e relatório. |
| `status` | sim | `available` ou `planned`. |
| `local_path` | sim | Fonte local do `SKILL.md`. |
| `bundle_path` | não | Diretório de skill quando a distribuição precisa de `SKILL.md`, `references/`, `assets/` e licença. |
| `plugin_path` | não | Mirror no plugin de orquestração quando a skill for parte do pacote SDD. |
| `plugin_bundle_path` | não | Diretório mirror do bundle no plugin de orquestração. |
| `source_repository` | não | Repositório upstream usado quando a skill for vendorizada. |
| `source_commit` | não | Commit upstream pinado para auditoria. |
| `license` | não | Licença preservada no bundle. |
| `signals` | não | Sinais esperados de projeto/stack. |
| `tags` | não | Metadados livres para descoberta futura. |
`available` exige que o arquivo exista e passe na validação. Quando `bundle_path` existe, o doctor valida também os arquivos essenciais do bundle. `planned` aparece no catálogo como backlog explícito e não bloqueia o doctor por ausência de arquivo.
## Formato de SKILL.md
O frontmatter mínimo é:
```md
---
name: <skill-id>
description: <quando usar e qual problema resolve>
---
```
Evite chaves como `allowed-tools`, `tools`, `model`, `version` ou metadados específicos de provider no frontmatter. O doctor exige `name` e `description`; bundles vendorizados podem preservar metadados upstream quando não quebram portabilidade. O corpo deve ser curto e operacional:
- `# <Nome>` com título claro;
- `## Objetivo`;
- `## Procedimento`;
- `## Regra` ou `## Regras`;
- `## Evidências`;
- `## Fallback`.
Skills SDD antigas podem manter corpo mais rico quando necessário, mas novas skills devem ser concisas e provider-neutral. Documentação longa deve ir para `references/` apenas quando realmente necessária e lida pela skill.
### Diretiva de idioma de output
Skills traduzidas para pt-br devem incluir uma diretiva `**Idioma de output:**` logo após o frontmatter, especificando que todo output gerado pela skill deve ser em PT-BR com acentuação preservada, mantendo código, CSS classes, identificadores e termos técnicos em inglês. Esta diretiva complementa a regra global de `output-quality` ("PT-BR com acentos onde for texto humano") e garante que agents que carregam a skill individualmente também respeitem o idioma.
## Skills distribuídas
O catálogo inclui os seguintes grupos principais.
| Grupo | Exemplos | Uso |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| SDD centrais | `orchestration`, `project-discovery`, `risk-classifier`, `traceability`, `checkpoints`, `memory` | Etapas e governança do fluxo SDD. |
| Complementares | `bdd-gherkin`, `code-review`, `artifact-schemas`, `test-strategy`, `security-privacy`, `data-contracts` | Qualidade, aceite, review, testes e risco. |
| Qualidade de geração | `output-quality`, `prompt-craft`, `humanizer`, `product-discovery-frameworks`, `execution-discipline` | Artefatos decisão-primeiro, prompts, prosa, discovery e execução. |
| Execução & debug | `systematic-debugging`, `subagent-orchestration`, `reflexion-loop` | Root-cause-first, Agent Teams, auto-correção pós-task. |
| Design craft | `frontend-design`, `interface-design`, `visual-review`, `design-tokens`, `design-extraction`, `impeccable-design` | UI com memória, deslop, auditoria de referência e vocabulário de direção (23 comandos). |
| Nicho no core | `frontend-slides`, `webgpu-threejs-tsl`, `nothing-design`, `ai-research-workflow` | Ativação por signal; não vão no hot path genérico de Idea→PRD. |
| Intake, arquitetura & triage | `grill-with-docs`, `grill-me`, `grilling`, `handoff`, `improve-codebase-architecture`, `triage`, `domain-modeling`, `codebase-design` | Context Harvest e entrevista de alto impacto antes da Idea/PRD/Tech Spec, handoff entre agents, deepening de módulos, triage de issues/PRs, ubiquitous language e ADRs leves. |
| Visual craft avançado | `high-end-visual-design` (tasteskill) | Anti-slop frontend para landing pages, portfolios e redesigns; pre-flight check rigoroso. |
| Stack/contexto | `react-frontend`, `rust-project`, `hono-api`, `ci-release`, `secrets-config`, `monorepo-context` | Projetos específicos, fora ou dentro do SDD. |
`bdd-gherkin` e `code-review` também são distribuídas no plugin de orquestração e nos mirrors `.agents/.claude` para manter paridade de pacote.
`diagram-design` é vendorizada como bundle gerenciado a partir de `https://github.com/cathrynlavery/diagram-design` no commit `0ab077f2291e9056554d48a90c4ff45f0b7029a5`, preservando a licença MIT. Ela é usada por `artifact-diagrams` para gerar companions HTML/SVG; Mermaid/Excalidraw continuam sendo o contrato versionável dos artefatos.
### Política de ingestão de skills externas
1. **Absorver princípios** em skills nativas (`output-quality`, `execution-discipline`, `frontend-design`, etc.) quando o valor for comportamento, não um design system completo.
2. **Vendor seletivo** com `source_repository` (+ `source_commit` quando pinado) e licença, no estilo de `diagram-design`, quando o material for bundle reutilizável.
3. **Nicho no core** fica `available` no catálogo com `signals`, mas **não** entra no frontmatter default de agents de etapa genérica.
4. Preferir skills curtas e provider-neutral; documentação longa em `references/` só quando a skill lê o arquivo.
Atribuições e fontes inspiradoras incluem prompt-master, humanizer, Anthropic skills, frontend-slides, webgpu-claude-skill, nothing-design-skill, Karpathy guidelines, agent-scripts (disciplina de forma), code-review-graph, interface-design, AI-Research-SKILLs, Product-Manager-Skills, superpowers (systematic-debugging, subagent-driven-development, test-driven-development), anydesign (design-extraction), context-engineering-kit (reflexion-loop), deep-research (ai-research-workflow modo deep research), impeccable (impeccable-design vocabulário de 23 comandos), a Philosophy of Software Design (codebase-design deep modules), Google Eng Practices (triage), domain-driven-design (domain-modeling ubiquitous language) e tasteskill (high-end-visual-design anti-slop frontend).
## Recomendações por stack
`sdd context recommend` detecta sinais do projeto e recomenda skills/rules. Exemplos de sinais:
| Sinal | Skill recomendada |
| ------------------------------------------------- | ------------------------------------------- |
| `package.json` com React/Next/Vite | `react-frontend` |
| `package.json` com Hono | `hono-api` |
| `Cargo.toml` com Axum/Actix/Tonic | `rust-api` |
| `Cargo.toml` sem API Rust | `rust-project` |
| `go.mod` | `go-project` |
| `.github/workflows`, `.gitlab-ci.yml`, Jenkins | `ci-release` |
| migrations/ORMs | `data-contracts-local` |
| OpenAPI/GraphQL/protobuf | `api-contracts` |
| `.env.example`, `wrangler.toml`, deploy config | `secrets-config` |
| `tests/`, Vitest/Jest/Pytest/Playwright | `test-strategy-local` |
| `three` / WebGPU / TSL / WGSL | `webgpu-threejs-tsl` |
| pedido de slides/deck/pitch | `frontend-slides` |
| direção Nothing / monochrome industrial | `nothing-design` |
| notebooks / fine-tune / eval LLM | `ai-research-workflow` |
| deep research / literature review / due diligence | `ai-research-workflow` (modo deep research) |
| dashboard/admin product UI | `interface-design` |
| screenshot / URL / Figma / design audit | `design-extraction` |
| ui-polish / design-review / ai-slop / typography | `impeccable-design` |
| bug / test failure / build failure | `systematic-debugging` |
| agent teams / parallel independent tasks | `subagent-orchestration` |
| pós-implementação / self-review / gap analysis | `reflexion-loop` |
| início de orquestração / Context Harvest | `grill-with-docs` |
| stress-test de ideia / design / plano | `grill-me`, `grilling` |
| handoff de contexto entre agents | `handoff` |
| oportunidades de deepening de módulos | `improve-codebase-architecture` |
| triage de issues / PRs externos | `triage` |
| ubiquitous language / glossário de domínio | `domain-modeling` |
| design de módulos / deep modules / seams | `codebase-design` |
| landing page / portfolio / redesign anti-slop | `high-end-visual-design` |
`sdd skills doctor --strict` valida que todos os IDs recomendados pelo projeto atual existem em `templates/skill-catalog.yaml`.
## Sync por cliente
`sdd skills sync` materializa skills `available` para os targets selecionados. Skills simples copiam só o `SKILL.md`; bundles copiam o diretório inteiro para preservar `references/`, `assets/` e `LICENSE`.
| Target | Destino |
| ------------------------- | ------------------------ |
| `codex` | `.agents/skills/<id>/` |
| `antigravity` | `.agents/skills/<id>/` |
| `claude` ou `claude-code` | `.claude/skills/<id>/` |
| `cursor` | `.cursor/skills/<id>/` |
| `devin` | `.devin/skills/<id>/` |
| `opencode` | `.opencode/skills/<id>/` |
| `trae` | `.trae/skills/<id>/` |
Use `--dry-run` para revisar o plano. Use `--force` somente quando quiser sobrescrever skills já existentes no projeto alvo.
## Doctor
`sdd skills doctor --strict` verifica:
- catálogo v1 bem formado;
- IDs sem duplicidade;
- `status` válido (`available|planned`);
- arquivo local da skill disponível;
- frontmatter com `name` e `description` preenchidos;
- corpo não vazio;
- bundle com `SKILL.md`, referências, assets essenciais e licença quando declarado;
- plugin mirror existente quando `plugin_path` for declarado;
- plugin bundle existente quando `plugin_bundle_path` for declarado;
- recomendações detectadas por stack cobertas pelo catálogo.
Saída JSON:
```json
{
"status": "pass",
"checked": ["orchestration", "react-frontend"],
"missing": [],
"invalid": [],
"planned": []
}
```
## Recommend
`sdd skills recommend` imprime uma visão do catálogo. Com `--write`, grava `.sdd/skill-recommendations.md` no projeto alvo. O arquivo é um relatório operacional, não fonte de verdade; a fonte de verdade continua sendo `templates/skill-catalog.yaml`.
## Relação com capabilities
`templates/capability-catalog.yaml` expõe:
- `skills-catalog`: descoberta/listagem do catálogo;
- `skills-doctor`: validação e sync;
- `dynamic-workflows`: integração com workflows determinísticos.
Rode:
```bash
sdd capabilities doctor --targets all
sdd clients doctor --strict
```
para validar a cobertura entre catálogo, clients e capabilities.
## Fluxo recomendado
```bash
sdd discover --name "<ciclo>"
sdd context recommend
sdd skills doctor --strict
sdd skills sync --targets codex,claude,cursor,devin,kiro,opencode,trae,antigravity --dry-run
sdd skills sync --targets codex,claude --force
sdd capabilities doctor --targets all
```
Quando uma nova stack aparecer, crie a skill em `.agents/skills/<id>/SKILL.md`, registre em `templates/skill-catalog.yaml`, rode `sdd skills validate`, depois `sdd skills doctor --strict`.