Yinyo Skill Craft — Skill 工匠
Ferramenta de auditoria de engenharia de Skill e correção interativa. Baseada no guia oficial da Perplexity Agents Team + nas convenções de codificação Karpathy CLAUDE.md + na experiência prática da série yinyo.
Nova capacidade: suporte a correção automática + modo de confirmação do usuário.
Regras principais
1. Skill é diretório, não arquivo
- Arquivo único > 50KB → deve ser dividido em estrutura hub-and-spoke
- Estrutura padrão: SKILL.md + README.md + docs/ + examples/ + subskills/
- Aninhamento múltiplo: 300 tópicos → 20 domínios → 15 tópicos/domínio
2. Description é o gatilho de roteamento
- Deve começar com
Load when... - Explica a condição de disparo, não é uma lista de funcionalidades
- Limite de 50 caracteres
3. Carregamento progressivo em três níveis
| Nível | Orçamento de Tokens | Conteúdo | Frequência de pagamento |
|---|---|---|---|
| Index | ~100 | nome + descrição | Por sessão |
| Body | ~5000 | Regras principais + referência rápida | Do carregamento até compactação |
| Runtime | Ilimitado | docs/ + examples/ + subskills/ | Quando usado |
4. Remover conteúdo conhecido pelo modelo
- Explicar conceitos básicos → remover
- Princípios gerais de programação → remover
- "Se é fácil de explicar, o modelo já sabe. Delete."
5. Os quatro princípios de codificação de Karpathy
- Think Before Coding: Se não tiver certeza, pergunte
- Simplicity First: Se 200 linhas resolvem, não escreva 500
- Surgical Changes: Mexa apenas no que precisa ser mexido
- Goal-Driven Execution: Defina metas verificáveis
Fluxo de correção interativa (novo)
Princípios de correção
- Baixo risco (estrutura, formato, versão) → execução automática, relatório posterior
- Médio risco (reescrita de descrição) → exibir comparação antes/depois, confirmação do usuário
- Alto risco (remoção de conteúdo) → listar itens a remover, confirmar um por um
Escopo da correção
| Tipo de correção | Exemplo | Nível de risco |
|---|---|---|
| Ajuste estrutural | Dividir arquivo único em diretório | Baixo |
| Reescrita de descrição | Mudar para Load when... | Médio |
| Remoção de conteúdo | Remover conteúdo conhecido pelo modelo | Alto |
| Sincronização de versão | Atualizar version/last_updated | Baixo |
| Padronização de formato | Completar frontmatter | Baixo |
Fluxo de correção
auditar → listar problemas → classificar riscos → confirmar usuário → corrigir automaticamente → auditar novamente → relatar resultados
Verificação pós-correção
- Executar automaticamente uma segunda auditoria
- Comparar pontuação antes e depois
- Gerar relatório de correção (o que foi alterado, por que foi alterado, mudança na pontuação)
Processo de auditoria
Entrada
O usuário fornece:
- Caminho do diretório da Skill, ou
- Conteúdo do SKILL.md
Saída
Gera relatório de auditoria:
## Relatório de auditoria: {skill-name}
### Auditoria estrutural
- [PASS/WARN/FAIL] Estrutura de diretórios
- [PASS/WARN/FAIL] Tamanho de arquivo
- [PASS/WARN/FAIL] Profundidade de aninhamento
### Auditoria de conteúdo
- [PASS/WARN/FAIL] Forma como Description é escrita
- [PASS/WARN/FAIL] Detecção de conteúdo conhecido pelo modelo
- [PASS/WARN/FAIL] Densidade de sinal
### Gerenciamento de versão
- [PASS/WARN/FAIL] Formato do número de versão
- [PASS/WARN/FAIL] Estado de sincronização
### Pontuação total: {X}/100
### Sugestões: {ações prioritárias}
Lista de detecção de antipadrões
Antipadrões estruturais
- Arquivo único inchado (> 50KB)
- Descrição muito longa (> 100 tokens)
- Sem hierarquia (> 50 tópicos planos)
- Sem gerenciamento de versão
Antipadrões de conteúdo
- Conteúdo conhecido pelo modelo (explicação de conceitos básicos)
- Engenharia excessiva (camadas de abstração > necessidade real)
- Encenação de processo (conformidade com restrições em vez de qualidade do produto final)
- Sem critérios de verificação
Armadilhas específicas da yinyo
- Hesitação em reverter versões (não reverter imediatamente em caso de queda de qualidade)
- Quanto mais completo o processo, pior a qualidade (lição do yinyo-writer)
- Arquivo único de 277KB (lição do yinyo-liuyao)
Modelo de sugestões de correção
Arquivo único inchado → Dividir
Original: SKILL.md (277KB)
Novo:
├── SKILL.md (5KB: regras principais)
├── docs/
│ ├── rules.md (50KB: 120 regras)
│ ├── examples.md (100KB: 412 exemplos de hexagramas)
│ └── reference.md (30KB: tabela de atribuição dos 64 hexagramas)
└── subskills/
├── edge-case-1.md
└── edge-case-2.md
Description incorreta → Corrigir
❌ "Esta Skill ajuda você a escrever artigos."
✅ "Carregue quando o usuário precisar escrever um artigo para conta pública do WeChat."
Referência rápida
Nomenclatura da Skill
yinyo-{domain}-{action}
Tamanho dos arquivos
- Index: < 1KB
- Body: < 50KB
- Runtime: Ilimitado
Gerenciamento de versão
- SemVer: MAJOR.MINOR.PATCH
- Sincronizar a cada atualização: SKILL.md + README.md + Git commit + memória
Palavras de ativação para correção
- "Corrigir esta Skill" → entra no modo de correção interativa
- "Correção automática" → executa correções de baixo risco
- "Ajuda a modificar" → exibe sugestões de alteração, aguarda confirmação