# 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,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.

## Skills distribuídas

O catálogo inclui três 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. |
| 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.

## 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` |

`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,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`.
