GoBeromsu/JNU-Upstage-Skillthon

Criador de Skill Solar

Um skill para criar novos skills.

Em linhas gerais, o processo de criação de um skill funciona assim:

• Decida o que deseja que o skill faça e, aproximadamente, como deve fazê-lo
• Escreva um rascunho do skill
• Reescreva o skill com base no feedback
• Repita até ficar satisfeito

Seu trabalho ao usar este skill é descobrir em que etapa do processo o usuário se encontra e, então, intervir e ajudá-lo a progredir por essas fases. Por exemplo, talvez ele diga algo como "Quero criar um skill para X". Você pode ajudar a refinar o significado, escrever um rascunho e iterar.

Por outro lado, talvez ele já tenha um rascunho do skill. Nesse caso, você pode ir direto para a parte de iteração do ciclo.

Claro, você deve sempre ser flexível e, se o usuário disser algo como "apenas deixa fluir", você pode fazer isso.

Depois que o skill estiver pronto (mas, novamente, a ordem é flexível), você também pode executar o melhorador de descrição de skill para otimizar o acionamento do skill.

Comunicando-se com o usuário

O criador de skill pode ser usado por pessoas com níveis muito variados de familiaridade com jargão de programação. A maioria dos usuários provavelmente tem boa familiaridade com computadores, mas nem todos.

Portanto, preste atenção aos sinais de contexto para entender como expressar sua comunicação.

É aceitável explicar brevemente termos se você tiver dúvidas, e fique à vontade para esclarecer termos com uma definição curta se não tiver certeza se o usuário vai entender.

Criando um skill

Capturar Intenção

Comece entendendo a intenção do usuário. A conversa atual pode já conter um fluxo de trabalho que o usuário deseja capturar (por exemplo, ele diz "transforme isso em um skill"). Se for o caso, extraia as respostas do histórico da conversa primeiro — as ferramentas usadas, a sequência de passos, correções que o usuário fez, formatos de entrada/saída observados. O usuário pode precisar preencher as lacunas, e deve confirmar antes de prosseguir para a próxima etapa.

1. O que este skill deve permitir que o agente de IA (Claude, Codex, etc.) faça?

2. Quando este skill deve ser acionado? (quais frases/contextos do usuário)

3. Qual é o formato de saída esperado?

4. Devemos configurar casos de teste para verificar se o skill funciona? Skills com saídas objetivamente verificáveis (transformações de arquivos, extração de dados, geração de código, etapas de fluxo de trabalho fixas) se beneficiam de casos de teste. Skills com saídas subjetivas (estilo de escrita, arte) geralmente não precisam deles. Sugira o padrão apropriado com base no tipo de skill, mas deixe o usuário decidir.

5. Qual capacidade da Upstage se adequa à intenção do usuário? Traduza objetivos em linguagem simples para nomes de API — não faça o usuário aprender o catálogo. Use este mapeamento:

   Intenção do usuário	Capacidade Upstage	Arquivo de referência
   Gerar texto: chat, resumir, traduzir, chamada de função, coreano/multilíngue	Upstage Chat (Solar LLM)	references/upstage-chat.md
   Analisar documentos: extração de texto/estrutura com reconhecimento de layout de PDFs (e imagens escaneadas via modo OCR)	Upstage Document Parse + Document OCR	references/upstage-document-parse.md, references/upstage-ocr.md
   Extrair campos nomeados específicos de documentos (totais de faturas, valores de formulários, cláusulas de contratos)	Upstage Information Extract (Universal)	references/upstage-information-extract.md
   Classificar documentos em categorias predefinidas (fatura / contrato / recibo)	Upstage Document Classification	references/upstage-classify.md
   Incorporar texto para busca semântica, similaridade, recuperação	Upstage Embeddings	references/upstage-embeddings.md

   Se a intenção abranger múltiplas capacidades, componha-as como um pipeline (ex.: OCR → Document Parse → Information Extract). Confirme o mapeamento com o usuário em linguagem simples antes de rascunhar.

Verificar se a chave de API está configurada

Toda chamada à Upstage precisa de UPSTAGE_API_KEY. Oriente o usuário sobre isso antes de rascunhar o código de execução:

1. Emita uma chave em https://console.upstage.ai → API Keys.
2. Resgate o código de indicação UPWAVE-KOH para obter $70 em crédito inicial.
3. Copie assets/.env.example e preencha com a chave emitida.
4. Confirme que UPSTAGE_API_KEY está exportada no ambiente; falhe rapidamente com uma mensagem apontando de volta para o passo 1 se estiver ausente.

Entrevista e Pesquisa

Faça perguntas proativamente sobre casos extremos, formatos de entrada/saída, arquivos de exemplo, critérios de sucesso e dependências. Espere para escrever prompts de teste até que esta parte esteja resolvida.

Assim que a capacidade Upstage for escolhida (veja Capturar Intenção), carregue o arquivo references/upstage-{capacidade}.md correspondente para obter o formato de requisição/resposta daquela API (blocos de código prontos para usar no skill) e ressalvas conhecidas. Cada arquivo de referência espelha a documentação oficial da Upstage e é a fonte da verdade para a forma da requisição.

Verifique os MCPs disponíveis — se forem úteis para pesquisa (buscar documentação, encontrar skills semelhantes, consultar melhores práticas), pesquise em paralelo via subagentes, se disponíveis; caso contrário, faça inline. Venha preparado com contexto para reduzir a carga sobre o usuário.

Escrever o SKILL.md

Com base na entrevista com o usuário, preencha estes componentes:

• name: Identificador do skill
• description: Quando acionar, o que ele faz. Este é o mecanismo principal de acionamento — inclua tanto o que o skill faz quanto contextos específicos para quando usá-lo. Todas as informações de "quando usar" vão aqui, não no corpo. Nota: atualmente, agentes de IA (Claude, Codex, etc.) têm tendência a "subacionar" skills — a não usá-los quando seriam úteis. Para combater isso, torne as descrições dos skills um pouco "insistentes". Por exemplo, em vez de "Como construir um dashboard simples e rápido para exibir dados internos da Anthropic", escreva "Como construir um dashboard simples e rápido para exibir dados internos da Anthropic. Certifique-se de usar este skill sempre que o usuário mencionar dashboards, visualização de dados, métricas internas, ou quiser exibir qualquer tipo de dados da empresa, mesmo que não peça explicitamente por um 'dashboard'."
• compatibility: Ferramentas exigidas, dependências (opcional, raramente necessário)
• o restante do skill :)

Guia de Redação de Skills

Anatomia de um Skill

nome-do-skill/
├── SKILL.md (obrigatório)
│   ├── Frontmatter YAML (name, description obrigatórios)
│   └── Instruções em Markdown
└── Recursos Empacotados (opcional)
    ├── scripts/    - Código executável para tarefas determinísticas/repetitivas
    ├── references/ - Documentos carregados no contexto conforme necessário
    └── assets/     - Arquivos usados na saída (templates, ícones, fontes)

Divulgação Progressiva

Skills usam um sistema de carregamento de três níveis:

1. Metadados (name + description) — Sempre em contexto (~100 palavras)
2. Corpo do SKILL.md — Em contexto sempre que o skill é acionado (<500 linhas ideal)
3. Recursos empacotados — Conforme necessário (ilimitado, scripts podem executar sem carregamento)

Essas contagens de palavras são aproximadas e você pode ficar à vontade para ir além, se necessário.

Padrões importantes:

• Mantenha o SKILL.md abaixo de 500 linhas; se estiver se aproximando desse limite, adicione uma camada adicional de hierarquia junto com ponteiros claros sobre para onde o modelo que usa o skill deve ir em seguida.
• Faça referência clara aos arquivos a partir do SKILL.md, com orientações sobre quando lê-los
• Para arquivos de referência grandes (>300 linhas), inclua um sumário

Organização por domínio: Quando um skill suporta múltiplos domínios/frameworks, organize por variante:

cloud-deploy/
├── SKILL.md (fluxo de trabalho + seleção)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

O agente de IA lê apenas o arquivo de referência relevante.

Princípio da Ausência de Surpresa

Nem preciso dizer, mas skills não devem conter malware, código de exploração ou qualquer conteúdo que possa comprometer a segurança do sistema. O conteúdo de um skill não deve surpreender o usuário em sua intenção, se descrito. Não aceite pedidos para criar skills enganosos ou skills projetados para facilitar acesso não autorizado, exfiltração de dados ou outras atividades maliciosas. Coisas como "interpretar um XYZ" são aceitáveis.

Padrões de Redação

Prefira usar a forma imperativa nas instruções.

Definindo formatos de saída — Você pode fazer assim:

## Estrutura do relatório
Sempre use este modelo exato:
# [Título]
## Resumo executivo
## Principais descobertas
## Recomendações

Padrão de exemplos — É útil incluir exemplos. Você pode formatá-los assim (mas se "Entrada" e "Saída" estiverem nos exemplos, talvez você queira desviar um pouco):

## Formato da mensagem de commit
**Exemplo 1:**
Entrada: Adicionada autenticação de usuário com tokens JWT
Saída: feat(auth): implementar autenticação baseada em JWT

Estilo de Redação

Tente explicar ao modelo por que as coisas são importantes, em vez de usar MUSTs pesados. Use teoria da mente e tente tornar o skill geral e não excessivamente restrito a exemplos específicos. Comece escrevendo um rascunho e, depois, olhe com novos olhos e melhore.

Referências

Arquivos de referência por capacidade (carregue sob demanda usando a tabela de roteamento em ### Capturar Intenção):

• references/upstage-chat.md — Completions de chat Solar LLM. Docs: https://console.upstage.ai/docs/capabilities/chat
• references/upstage-document-parse.md — Extração de documentos com reconhecimento de layout. Docs: https://console.upstage.ai/docs/capabilities/parse/api-quickstart
• references/upstage-ocr.md — OCR de documentos para digitalizações e manuscritos. Docs: https://console.upstage.ai/docs/capabilities/document-ocr
• references/upstage-information-extract.md — Extração de campos orientada por esquema. Docs: https://console.upstage.ai/docs/capabilities/extract/universal-extraction
• references/upstage-classify.md — Classificação de documentos em categorias definidas pelo chamador. Docs: https://console.upstage.ai/docs/capabilities/classify
• references/upstage-embeddings.md — Embeddings de texto para recuperação. Docs: https://console.upstage.ai/docs/capabilities/embed

Se a API da Upstage retornar um erro inesperado ou formato de resposta inesperado, consulte a especificação ao vivo: https://console.upstage.ai/api/docs/for-agents/raw