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>
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 | Regras oficiais do ecossistema - documento mestre | ~477 | Crítica |
| 1 | SKILL-BEST-PRACTICES.md | Guia completo para criação de skills de alta qualidade | ~600 | Alta |
| 2 | AGENT-BEST-PRACTICES.md | Guia para agentes especializados | ~471 | Alta |
| 3 | 03-GUIA-HOOKS.md | NOVO - Guia completo de hooks (12 eventos, scripts, debugging) | ~1184 | Alta |
| 4 | 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
---
name: skill-name
description: Capacidade. Use when [triggers].
---
# Título
[Instruções <500 linhas]
Estrutura Agent
---
name: agent-slug
description: Especialização. Use for [triggers].
model: sonnet
tools: [lista]
---
# Nome
[Persona + Workflow + Limites]
Estrutura Hook
{
"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.jsoncom 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
Repositórios
Análises
Última actualização: 2026-02-04 | Descomplicar®