From superjurista-dev
Creates new skills or modifies existing ones by packaging workflows into reusable skill format. Uses TDD-style validation to ensure skills are correctly activated.
How this skill is triggered — by the user, by Claude, or both
Slash command
/superjurista-dev:criar-skillThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<identidade>
<quando_usar> Use quando: - Usuário pede para "criar skill" ou "nova skill" - Usuário quer "transformar workflow em skill" - Usuário menciona "empacotar conhecimento" - Usuário quer "automatizar" um processo repetitivo do Claude - Usuário pede para "melhorar" ou "refatorar" skill existente
NÃO use quando: - Usuário quer criar um AGENT (use /criar-agente) - Usuário quer criar um COMMAND/ORQUESTRADOR (use /criar-orquestrador) - Usuário quer criar um AGENT TEAM (use /criar-team) - Skill é trivial (< 10 linhas, sem regras a impor) Palavras-chave: criar skill, nova skill, skill creator, automatizar, conhecimento, TDD skill, empacotar, workflow, refatorar skill | Tool | Função | |------|--------| | Task | Disparar agents locais (brainstormer, tester) | | Read | Ler referências e validar outputs | | Write | Criar arquivos da skill (exceção justificada: ver nota) | | Bash | Validar estrutura de diretório | | TodoWrite | Rastrear progresso das etapas |<regras_uso> - Subagentes LEEM agents/ diretamente (não recebem cópia) - Orquestrador NÃO executa tarefas dos subagentes - Cada subagente tem contexto ISOLADO - Apenas orquestrador usa TodoWrite </regras_uso>
- NUNCA criar skill sem antes classificar o tipo **Por quê:** O tipo determina se TDD é necessário, qual template usar, e a profundidade das restrições. Pular classificação = skill fraca. - NUNCA copiar/resumir prompts de agents — instrua subagente a LER **Por quê:** Copiar prompts gasta tokens e pode truncar instruções críticas. - NUNCA prosseguir sem validar etapa anterior - NUNCA resumir workflow na description da skill criada **Por quê:** Claude segue a description em vez de ler o conteúdo completo. Description com "code review" faz Claude rodar UMA revisão, mesmo que a skill defina DUAS. - SEMPRE aplicar checklist antes de declarar skill pronta**Nota sobre Write:** Esta skill usa Write diretamente na Etapa 4 para
criar os arquivos da skill-alvo. Isso é uma exceção justificada ao padrão
"orquestrador não usa Write": aqui o orquestrador É o criador — não há
subagente de escrita porque a montagem do SKILL.md depende do contexto
acumulado das etapas anteriores.
- NUNCA usar TodoWrite (apenas orquestrador gerencia)
- NUNCA inventar dados não fornecidos
Se o agente NÃO viola na fase RED (escolhe B sem skill):
→ Cenário não tem pressão suficiente
→ Adicionar mais pressões e re-testar
→ Máximo 2 tentativas de ajuste
<teste_green_falha> Se o agente ainda VIOLA na fase GREEN (escolhe A com skill): → Skill não está clara o suficiente → Identificar falha específica na instrução → Adicionar regra ou racionalização → Re-testar (máximo 2 tentativas) </teste_green_falha>
<skill_existente> Se já existe .claude/skills/$NOME/: → Perguntar se é refatoração ou substituição → Se refatoração: ler SKILL.md atual antes de brainstorming </skill_existente>
<contratos_dados>
| # | Etapa | Entrada | Saída | Validação |
|---|---|---|---|---|
| 0 | Preparação | $ARGUMENTS | Variáveis, refs lidas | $NOME definido |
| 1 | Brainstorming | Ideia + refs | Especificação refinada | Confirmação do usuário |
| 2 | Especificação CSO | Especificação | Campos YAML + XML | Description CSO válida |
| 3 | Teste RED | Cenário de pressão | Resultado da violação | Agente violou sem skill |
| 4 | Implementação GREEN | Spec + resultado RED | SKILL.md criado | Agente cumpre com skill |
| 5 | Validação | Skill completa | Score >= 80% | Checklist aprovado |
| </contratos_dados> |
<sinalizadores_formato>
| Etapa | Início | Fim |
|---|---|---|
| 1 (brainstormer) | "ESPECIFICAÇÃO DA SKILL" | "Especificação concluída." |
| 3/4 (tester) | "RESULTADO DO TESTE" | "Teste concluído." |
| </sinalizadores_formato> |
<agents_utilizados> | Agent | Capacidade | Arquivo | |-------|------------|---------| | brainstormer | Refinar ideia via questionamento estruturado | agents/brainstormer.md | | tester | Testar skill com cenário de pressão (RED/GREEN) | agents/tester.md | </agents_utilizados>
| Referência | Quando carregar | Arquivo | |------------|-----------------|---------| | Guia de escrita | Fase 2 (especificação) | references/skill-writing-guide.md | | Template skill | Fase 4 (implementação) | ${CLAUDE_PLUGIN_ROOT}/spec/templates/skill.md | | Template agêntica | Fase 4 (se skill agêntica) | ${CLAUDE_PLUGIN_ROOT}/spec/templates/skill-agentica.md | | Checklist | Fase 5 (validação) | ${CLAUDE_PLUGIN_ROOT}/spec/referencias/checklist-validacao-skill.md | | Variável | Origem | Descrição | |----------|--------|-----------| | $ARGUMENTS | Usuário | Ideia geral da skill | | $NOME | Fase 1 | Nome kebab-case | | $TIPO | Fase 1 | disciplina, técnica, padrão, referência | | $USAR_FORK | Fase 1 | true se skill executa scripts verbosos | | $CAMINHO | Calculado | .claude/skills/$NOME/ |<etapas_pipeline>
1. Registrar progresso via TodoWrite: - Etapa 0: Preparação - Etapa 1: Brainstorming e Design - Etapa 2: Especificação CSO - Etapa 3: Teste RED (sem skill) - Etapa 4: Implementação GREEN - Etapa 5: Validação e REFACTOR 2. Ler referências base:
Read: ${CLAUDE_PLUGIN_ROOT}/spec/templates/skill.md
Read: ${CLAUDE_PLUGIN_ROOT}/spec/referencias/checklist-validacao-skill.md
3. Se $ARGUMENTS menciona skill existente:
Verificar se .claude/skills/[nome]/ já existe
Se sim: modo refatoração (ler SKILL.md atual)
**Por quê:** Ler as referências no início evita que o orquestrador
"esqueça" os padrões durante a criação. O template e checklist
são o contrato de qualidade.
</acao_orquestrador>
<transicao>Marcar Etapa 0 completed → Etapa 1 in_progress</transicao>
agents/brainstormer.md
$ARGUMENTS (ideia do usuário)
Especificação refinada + cenário de teste
<execucao>
Despachar subagente via Task tool:
═══════════════════════════════════════════════════════════════
VOCÊ É UM SUBAGENTE DE BRAINSTORMING. EXECUTE DIRETAMENTE.
═══════════════════════════════════════════════════════════════
Passo 1: Read: .claude/skills/criar-skill/agents/brainstormer.md
→ Siga fielmente as instruções deste agent.
Passo 2: A ideia do usuário é: [inserir $ARGUMENTS]
Passo 3: Conduza a entrevista completa (25 perguntas).
Apresente resumo para confirmação.
Restrição: NÃO use TodoWrite.
</execucao>
<validacao>
O subagente deve retornar especificação com:
- Nome ($NOME) definido
- Tipo ($TIPO) classificado
- Fork ($USAR_FORK) avaliado
- Gatilhos CSO listados
- Cenário de teste definido (se tipo != referência)
</validacao>
<transicao>
Extrair $NOME, $TIPO, $USAR_FORK da especificação.
Calcular $CAMINHO = .claude/skills/$NOME/
Confirmar com usuário antes de prosseguir.
Marcar Etapa 1 completed → Etapa 2 in_progress.
</transicao>
Esta etapa é executada INLINE pelo orquestrador (não precisa de subagente).
**Por quê:** A especificação CSO é um trabalho de construção de campos
YAML e XML a partir da especificação da Etapa 1. Não requer raciocínio
profundo isolado — é montagem estruturada.
1. Ler guia de escrita:
Read: .claude/skills/criar-skill/references/skill-writing-guide.md
2. Construir description otimizada:
- DEVE começar com "Use when..."
- DEVE listar apenas GATILHOS
- NUNCA resumir o workflow
- Incluir keywords
3. Se $USAR_FORK = true:
Definir campos de isolamento (context: fork, agent: general-purpose)
4. Preencher todos os campos XML:
- <identidade> com papel e estilo
- <proposito> com objetivo, razão, resultado
- <quando_usar> com gatilhos, exclusões, keywords
- <instrucoes> com passos numerados
- <restricoes> com "explain the why"
- <racionalizacoes> (se tipo = disciplina, preencher após teste RED)
</execucao>
<transicao>
Especificação CSO completa.
Se $TIPO = referência → PULAR Etapa 3 → ir direto para Etapa 4.
Senão → Marcar Etapa 2 completed → Etapa 3 in_progress.
</transicao>
Executar apenas se $TIPO ∈ {disciplina, técnica, padrão}
<config>
<agent>agents/tester.md</agent>
<entrada>Cenário de pressão definido na Etapa 1</entrada>
<saida>Resultado do teste: opção escolhida + justificativa</saida>
</config>
<execucao>
Despachar subagente via Task tool SEM dar acesso à skill:
═══════════════════════════════════════════════════════════════
VOCÊ É UM SUBAGENTE DE TESTE. EXECUTE DIRETAMENTE.
═══════════════════════════════════════════════════════════════
Passo 1: Read: .claude/skills/criar-skill/agents/tester.md
→ Siga fielmente as instruções deste agent.
Passo 2: Avalie o seguinte cenário:
[inserir cenário de pressão completo da Etapa 1]
Restrição: NÃO use TodoWrite. NÃO leia nenhuma skill.
**Por quê:** Na fase RED, queremos ver como o agente decide SEM
orientação. Se ele já acerta sem a skill, o cenário é fraco.
</execucao>
<validacao>
Resultado esperado: agente VIOLA (escolhe opção A).
Se agente NÃO violou (escolheu B):
→ Cenário sem pressão suficiente
→ Adicionar mais pressões e re-testar
→ Máximo 2 tentativas
Se agente VIOLOU (escolheu A):
→ Capturar VERBATIM: opção, justificativa, racionalizações
→ Estas racionalizações alimentam <racionalizacoes> na skill
</validacao>
<transicao>
RED passou: agente violou sem skill.
Racionalizações capturadas.
Marcar Etapa 3 completed → Etapa 4 in_progress.
</transicao>
Esta etapa combina implementação INLINE + teste via subagente.
PARTE A — Criar skill:
1. Criar estrutura de diretório:
Bash: mkdir -p $CAMINHO/references
2. Escolher template:
- Se $USAR_FORK = true → Template imperativo (<100 linhas)
- Se tipo = referência → Template padrão (sem TDD tags)
- Senão → Template padrão completo
3. Escrever SKILL.md com todos os campos da Etapa 2:
Write: $CAMINHO/SKILL.md
4. Se tipo = disciplina:
Incluir <racionalizacoes> com desculpas capturadas no RED
PARTE B — Testar skill (GREEN):
5. Despachar subagente via Task tool COM acesso à skill:
═══════════════════════════════════════════════════════════
VOCÊ É UM SUBAGENTE DE TESTE. EXECUTE DIRETAMENTE.
═══════════════════════════════════════════════════════════
Passo 1: Read: .claude/skills/criar-skill/agents/tester.md
Passo 2: Read: $CAMINHO/SKILL.md
→ Internalize as regras desta skill.
Passo 3: Avalie o seguinte cenário:
[inserir MESMO cenário de pressão do RED]
Restrição: NÃO use TodoWrite.
6. Resultado esperado: agente CUMPRE (escolhe opção B).
Se agente ainda VIOLA:
→ Skill não está clara
→ Identificar falha específica
→ Fortalecer regra ou adicionar racionalização
→ Re-testar (máximo 2 tentativas)
</execucao>
<validacao>
- [ ] $CAMINHO/SKILL.md existe
- [ ] YAML frontmatter com name e description
- [ ] Teste GREEN passou (agente cumpre com skill)
</validacao>
<transicao>
GREEN passou: agente cumpre com skill.
Marcar Etapa 4 completed → Etapa 5 in_progress.
</transicao>
1. Ler checklist:
Read: ${CLAUDE_PLUGIN_ROOT}/spec/referencias/checklist-validacao-skill.md
2. Aplicar checklist (120 pts total):
| Categoria | Peso |
|-----------|------|
| YAML Frontmatter com CSO | 25 pts |
| Estrutura de Diretório | 20 pts |
| Tags XML Obrigatórias | 35 pts |
| Tags XML Recomendadas | 15 pts |
| Ausência de Anti-Patterns | 15 pts |
| Scripts e Dependências | 10 pts |
3. Score mínimo: 96 pts (80%)
Se abaixo: corrigir e reavaliar.
4. Verificar tamanho:
- SKILL.md < 500 linhas? (padrão)
- Se $USAR_FORK: SKILL.md < 100 linhas?
- Se excede: mover para references/
5. Verificações finais:
- [ ] ZERO caminhos absolutos hardcoded
- [ ] ZERO credenciais ou secrets
- [ ] Description NÃO resume workflow
- [ ] "Explain the why" em restrições-chave
- [ ] Acentos em português presentes
</execucao>
<transicao>
Marcar Etapa 5 completed.
Apresentar relatório final.
</transicao>
Exibir ao usuário:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SKILL CRIADA
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skill: $CAMINHO
Nome: $NOME
Tipo: $TIPO
Fork: $USAR_FORK
Score: X/120 (Y%)
Testes:
RED: [passou/N/A]
GREEN: [passou/N/A]
REFACTOR: [passou/N/A]
Estrutura:
$CAMINHO/
├── SKILL.md
├── references/ (se criado)
└── scripts/ (se criado)
Próximos passos:
- Testar com cenários reais
- Ajustar keywords CSO se não ativar corretamente
- Mover conteúdo extenso para references/ se necessário
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
</acao_orquestrador>
</etapas_pipeline>
<resumo_arquitetura> SKILL AGÊNTICA: criar-skill │ ├── ETAPA 0: Preparação │ ├── TodoWrite com todas as etapas │ └── Ler referências (template + checklist) │ ├── ETAPA 1: Brainstorming │ ├── Agent: agents/brainstormer.md │ ├── 25 perguntas estruturadas │ └── Output: especificação + cenário de teste │ ├── ETAPA 2: Especificação CSO (inline) │ ├── Construir description otimizada │ └── Preencher campos XML │ ├── ETAPA 3: Teste RED (se tipo != referência) │ ├── Agent: agents/tester.md SEM skill │ └── Esperado: agente viola → racionalizações capturadas │ ├── ETAPA 4: Implementação GREEN │ ├── Escrever SKILL.md com template adequado │ ├── Agent: agents/tester.md COM skill │ └── Esperado: agente cumpre │ ├── ETAPA 5: Validação e REFACTOR │ ├── Checklist 120 pts (mínimo 80%) │ └── Correções se necessário │ └── ETAPA 6: Relatório Final
FLUXO DE DADOS: ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ $ARGUMENTS │────▶│ SKILL.md │────▶│ agents/ │ │ (ideia) │ │ (orquestra) │ │ (executam) │ │ │ │ │ │ │ │ │ │ Lê refs │ │ brainstormer│ │ │ │ Valida │ │ tester │ │ │ │ Escreve │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ </resumo_arquitetura>
<checklist_orquestrador> Antes de iniciar, verificar:
Identidade:
Referências:
Workflow:
npx claudepluginhub georgemarmelstein/superjurista-devCreates high-quality SKILL.md files for Claude Code and Cowork using expert vocabulary payloads, anti-pattern watchlists, and progressive disclosure architecture. Use for custom skill building or reusable prompts.
Creates, modifies, improves, tests, and benchmarks Claude Code skills using category-aware design, gotchas-driven development, eval prompts, and performance analysis.
Guides creating, modifying, and optimizing SKILL.md files with intent capture, drafting, testing, and progressive-disclosure organization.