Emanuel Almeida
692475a315
- Execute all 6 migrations on Desk CRM production database - Create missing tables: cr_lsps, cr_agent_lsps, cr_lsp_usage - Create archive tables: cr_*_usage_archive (4 tables) - Create system tables: cr_migrations, cr_maintenance_log - Make all scripts executable (chmod +x) - Total cr_* tables: 38 Migration files: - 001_initial_schema.sql - 002_add_lsps.sql - 003_add_relationships.sql - 004_add_telemetry.sql - 005_add_archive_tables.sql - 006_add_maintenance_log.sql Scripts: - session-init.sh, session-end.sh - inject-context.sh, inject-agent-context.sh - record-usage.sh, db-backup.sh, sync-to-mysql.sh Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
212 lines
5.8 KiB
Markdown
Executable File
212 lines
5.8 KiB
Markdown
Executable File
# 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®
|