# skillcheck

Linter de CI para skills, plugins e MCP servers de agentes de IA.

Skills, arquivos `CLAUDE.md`/`SKILL.md` e manifests de MCP server referenciam links, comandos
e caminhos que a IA segue às cegas. Nada valida isso hoje — se um link vira 404 ou um comando
muda de flag, a skill quebra silenciosamente na produção do usuário.

`skillcheck` escaneia um diretório e verifica se os links `http(s)` citados em Markdown
realmente respondem, sinalizando os quebrados com exit code diferente de zero (pronto pra CI).

## Uso

```bash
npx skillcheck ./minha-skill
```

```
skillcheck: escaneando links em ./minha-skill

✓ [200] https://github.com/exemplo
✗ [404] https://github.com/settings/developer_program

2 link(s) verificado(s), 1 quebrado(s).
```

Links dentro de blocos de código (```` ``` ````) não são checados — são exemplos de saída, não links vivos.

### Opções

| Flag | Padrão | Descrição |
| --- | --- | --- |
| `--json` | — | Saída em JSON, pra consumir em CI |
| `--concurrency <n>` | `8` | Checagens simultâneas |
| `--timeout <ms>` | `8000` | Timeout por link |
| `--ignore <domínio>` | — | Domínio extra a ignorar (repetível) |

Domínios de exemplo (`example.com`, `your-website.com`, `localhost`, etc.) já vêm ignorados por padrão.

### Resiliência

- **Retry com backoff exponencial** em erro de rede (300ms, 600ms, ...) antes de marcar como quebrado
- **HTTP 429 (rate limit) não conta como quebrado** — aparece com aviso (`⚠`), mas não falha o CI, já que é limite do servidor, não prova de link morto
- **Pontuação de frase colada na URL** (`...veja o link.` → o `.` final não vira parte do link) é removida automaticamente
- Aceita apontar direto pra um arquivo único, não só diretório: `skillcheck ./SKILL.md`

## Rodar como servidor MCP (qualquer CLI de IA)

Além do CLI de terminal, `skillcheck` roda como **servidor MCP via stdio** — assim qualquer cliente
compatível com Model Context Protocol (Claude Code, Cursor, Windsurf, etc.) chama a checagem de
links como ferramenta nativa, sem precisar dar shell out.

```bash
skillcheck mcp
```

Configuração de exemplo (`.mcp.json` ou equivalente do seu cliente):

```json
{
  "mcpServers": {
    "skillcheck": {
      "command": "npx",
      "args": ["skillcheck", "mcp"]
    }
  }
}
```

Isso expõe a ferramenta `check_links(path, ignoreDomains?)`, que retorna o mesmo JSON do modo `--json`
do CLI.

## Roadmap

- [x] Checagem de links HTTP(S) em Markdown
- [x] Ignora blocos de código e domínios de exemplo
- [x] Checagem concorrente com retry e backoff
- [x] Saída em JSON + CI de exemplo (dogfood) no próprio repo
- [x] Servidor MCP (`skillcheck mcp`) — roda em qualquer CLI de IA compatível
- [ ] Validação de manifests de MCP server (JSON schema)
- [ ] Checagem de comandos/flags de CLI citados no texto
- [ ] Ação de GitHub reutilizável (`skillcheck-action`)

## Desenvolvimento

```bash
npm install
npm run build
node dist/cli.js <diretório>
```

## Licença

MIT