# Boas Práticas SDK Claude Code Descomplicar®

> **Guias de Referência para Refactoring de Skills, Agents, Plugins e Hooks**

## Documentos Disponíveis

| # | Documento | Descrição | Linhas | Prioridade |
|---|-----------|-----------|--------|------------|
| 0 | [STANDARDS.md](STANDARDS.md) | **Regras oficiais do ecossistema** - documento mestre | ~477 | **Crítica** |
| 1 | [SKILL-BEST-PRACTICES.md](SKILL-BEST-PRACTICES.md) | Guia completo para criação de skills de alta qualidade | ~600 | Alta |
| 2 | [AGENT-BEST-PRACTICES.md](AGENT-BEST-PRACTICES.md) | Guia para agentes especializados | ~471 | Alta |
| 3 | [03-GUIA-HOOKS.md](03-GUIA-HOOKS.md) | **NOVO** - Guia completo de hooks (12 eventos, scripts, debugging) | ~1184 | Alta |
| 4 | [GUIA-PLUGINS-CLAUDE-CODE.md](GUIA-PLUGINS-CLAUDE-CODE.md) | Guia de arquitectura e estrutura de plugins | ~1167 | Alta |

---

## Resumo Executivo

### Skills - Pontos Críticos

| Factor | Impacto |
|--------|---------|
| **Descrição optimizada** | 20% → 72% taxa de activação |
| **Keywords específicas** | +5 keywords = melhor discovery |
| **Tamanho <500 linhas** | Performance e manutenibilidade |
| **Progressive disclosure** | Eficiência de tokens |

### Agents - Pontos Críticos

| Factor | Impacto |
|--------|---------|
| **Mapeamento MCPs** | Capacidades disponíveis |
| **Colaborações definidas** | Delegação eficiente |
| **Limites explícitos** | Evita scope creep |
| **Skills preloaded** | Contexto especializado |

### Hooks - Pontos Críticos

| Factor | Impacto |
|--------|---------|
| **12 eventos disponíveis** | Controlo total do ciclo de vida |
| **PreToolUse blocking** | Validação antes de execução |
| **Async para side-effects** | Não bloqueia Claude |
| **Agent hooks** | Multi-turn com tool access |

### Plugins - Pontos Críticos

| Factor | Impacto |
|--------|---------|
| **Progressive disclosure** | Metadata → Body → Resources |
| **Namespacing** | Evita colisões de comandos |
| **Versionamento semver** | Gestão de breaking changes |
| **CHANGELOG obrigatório** | Rastreabilidade completa |

---

## Taxas de Sucesso por Optimização

### Skills

```
Sem optimização     ████░░░░░░░░░░░░  20%
Descrição opt.      ██████████░░░░░░  50%
+ Keywords          ██████████████░░  72%
+ Hooks avaliação   ████████████████  84%
```

### Agents

```
Sem relacionamentos ██████░░░░░░░░░░  30%
+ MCPs mapeados     ██████████░░░░░░  55%
+ Skills integradas █████████████░░░  75%
+ Colaborações      ████████████████  90%
```

---

## Quick Reference

### Estrutura Skill

```yaml
---
name: skill-name
description: Capacidade. Use when [triggers].
---

# Título
[Instruções <500 linhas]
```

### Estrutura Agent

```markdown
---
name: agent-slug
description: Especialização. Use for [triggers].
model: sonnet
tools: [lista]
---

# Nome
[Persona + Workflow + Limites]
```

### Estrutura Hook

```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.sh"
      }]
    }]
  }
}
```

### Estrutura Plugin

```
plugin-name/
├── .claude-plugin/plugin.json    # Manifesto
├── skills/                       # Skills bundled
├── agents/                       # Agents bundled
├── commands/                     # Comandos /plugin:cmd
├── hooks/hooks.json              # Hooks do plugin
└── README.md
```

---

## Checklist Rápido

### Nova Skill

- [ ] Description com triggers e keywords
- [ ] SKILL.md <500 linhas
- [ ] Exemplos input/output
- [ ] Limites definidos
- [ ] Testada 3+ cenários

### Novo Agent

- [ ] MCPs mapeados por tipo (primary/recommended/available)
- [ ] Skills associadas
- [ ] Colaborações definidas
- [ ] Workflow documentado
- [ ] Limites explícitos

### Novo Hook

- [ ] Evento correcto (PreToolUse, PostToolUse, etc.)
- [ ] Matcher com regex válido
- [ ] Script executável (`chmod +x`)
- [ ] JSON output válido
- [ ] Timeout apropriado
- [ ] Async se side-effect

### Novo Plugin

- [ ] `.claude-plugin/plugin.json` com campos obrigatórios
- [ ] Versão semver correcta
- [ ] CHANGELOG.md actualizado
- [ ] README.md com contagens
- [ ] Namespacing para commands
- [ ] Testado em ambiente limpo

---

## Eventos de Hook Disponíveis

| Evento | Bloqueia? | Uso Principal |
|--------|-----------|---------------|
| SessionStart | Não | Setup ambiente, env vars |
| UserPromptSubmit | Sim | Validar/enriquecer prompt |
| PreToolUse | Sim | Bloquear comandos perigosos |
| PermissionRequest | Sim | Auto-aprovar/negar |
| PostToolUse | Não | Format, log, notify |
| PostToolUseFailure | Não | Error handling |
| SubagentStart | Não | Injectar contexto |
| SubagentStop | Sim | Validar resultado |
| Stop | Sim | Verificar antes de parar |
| PreCompact | Não | Preparar compactação |
| SessionEnd | Não | Cleanup, telemetria |

---

## Fontes

### Documentação Oficial
- [Claude Code Skills](https://code.claude.com/docs/en/skills)
- [Claude Code Hooks](https://code.claude.com/docs/en/hooks)
- [Claude Code Hooks Guide](https://code.claude.com/docs/en/hooks-guide)

### Repositórios
- [anthropics/skills](https://github.com/anthropics/skills) (62k stars)
- [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
- [claude-code-hooks-mastery](https://github.com/disler/claude-code-hooks-mastery)

### Análises
- [Claude Skills Deep Dive](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/)
- [Complete guide to hooks - Eesel AI](https://www.eesel.ai/blog/hooks-in-claude-code)

---

**Última actualização:** 2026-02-04 | Descomplicar®