# Contribuir com uma skill

As alterações no catálogo mantido pelo projeto são revisadas pelo mantenedor. Usuários podem publicar diretamente no próprio espaço após validação automática; consulte [PUBLISHING.md](PUBLISHING.md). Enquanto não houver repositório remoto definido, prepare as mudanças no diretório local; posteriormente, o mesmo fluxo pode ser usado por pull request.

## Estrutura obrigatória

Crie `skills/seu-identificador/` contendo `skill.json`, `SKILL.md` e `LICENSE`. Consulte uma das skills iniciais como exemplo. Os identificadores usam letras minúsculas ASCII, números e hífens, sem hífens consecutivos, até 64 caracteres. O frontmatter YAML de `SKILL.md` deve conter `name` igual ao identificador e `description` igual à descrição em `skill.json`.

O contrato de metadados fica em `schemas/skill.schema.json`. Declare autor, licença, categoria, tags, versão, compatibilidade, dependências, permissões e resumo das mudanças. A categoria deve constar em `catalog.config.json`. O rótulo `agent-skills` declara o formato de instruções, não certificação com um agente específico.

Adicione `scripts/`, `references/` e `assets/` apenas quando necessários. Não inclua credenciais, arquivos privados, diretórios ocultos, ambientes virtuais ou links simbólicos. Os pacotes não podem exceder 20 MiB de conteúdo. Inclua o texto da licença em `LICENSE` e tenha direito de distribuir todos os arquivos.

## Revisão e versão

1. Confira se a descrição permite identificar quando usar a skill.
2. Revise se as instruções preservam o pedido do usuário e declaram os requisitos reais.
3. Execute `python scripts/catalog.py validate`.
4. Para uma alteração em conteúdo já lançado, aumente `version` e atualize `changelog`.
5. Execute `python scripts/catalog.py release`, depois `python scripts/catalog.py build`.
6. Execute `python -m unittest discover -s tests -v` e revise a página e o pacote gerados.
7. Inclua os novos snapshots de `releases/` junto com as fontes na revisão. Nunca edite nem exclua uma versão já distribuída.

## Retirar uma versão

Adicione uma entrada ao objeto `withdrawn` de `catalog.config.json`, por exemplo:

```json
{"revisar-csv@1.0.0": "Motivo concreto da retirada"}
```

Reconstrua o site. A skill passa a recomendar a maior versão ainda ativa. Se todas forem retiradas, deixa de aparecer nos resultados. O histórico permanece acessível e o instalador recusa a versão retirada.

## Fontes

- [Especificação Agent Skills](https://agentskills.io/specification): estrutura de instruções e recursos.
- [JSON Schema validator](https://python-jsonschema.readthedocs.io/en/stable/validate/): validação do contrato local.