DEV Community

Captain
Captain

Posted on

Compartilhamento de Ideias para Design de Skills Chamadas de Interface OneService com Um Clique

#coding #programming #ai #beginners

Visão Geral

Definições de Termos

  • SKILL: originalmente uma funcionalidade do Claude AI, permite que usuários salvem processos complexos e multi-etapas (como limpeza de dados, formatação de conteúdo, análises específicas etc.) como “habilidades” reutilizáveis, melhorando o desempenho em tarefas específicas.

  • OneService (doravante OS): plataforma de serviço de dados desenvolvida pelo time Byte. Facilita transformar consultas SQL de diversas fontes de dados em APIs rapidamente, oferecendo criação, gerenciamento, operação e compartilhamento em todo o ciclo de vida.

  • PSM: identificador único de serviço interno da Byte.

Contexto do Projeto

Para desenvolvedores de backend, adicionar novos indicadores em uma página de lista é uma demanda comum.
Em projetos complexos, os dados desses indicadores geralmente vêm de fontes distribuídas em múltiplos bancos de dados. Antes, obtê-los envolvia duas abordagens relativamente pesadas:

  1. Chamar RPCs existentes que acessavam diversos bancos de dados;

  2. Conectar diretamente ao banco de dados atual e consultar tabelas brutas.

O uso do OS simplificou muito este trabalho, permitindo transformar consultas em APIs rapidamente, tornando a coleta de dados multi-fonte mais leve e eficiente.

Novos Problemas Identificados

Ao adicionar múltiplos indicadores vindos de diferentes fontes, era necessário criar vários APIs OS, cujas lógicas de chamada eram quase idênticas, mudando apenas API ID, parâmetros de entrada e saída.
Essa repetição mecânica expos a dor crônica da equipe no uso de APIs OS.

Principais Dores do Time

Nos PSM internos, as chamadas a APIs OS apresentavam problemas recorrentes:

  1. Baixa eficiência de criação: cada novo indicador exige escrever código muito parecido repetidamente, aumentando o risco de erro;

  2. Chamadas não uniformes: diferentes desenvolvedores usam SDKs OS de formas distintas (nomenclatura, parâmetros, passagem de argumentos), dificultando manutenção;

  3. Desenvolvimento e integração duplicados: um mesmo API ID pode ser implementado várias vezes, espalhando a lógica;

  4. Difícil localização e reutilização: falta de documentação ou anotações padronizadas, dependência de hábitos individuais;

  5. Nomeação e organização de arquivos confusas: métodos e arquivos dispersos, dificultando agregação e padronização de capacidades similares.

Por que escolher SKILL?

Definição resumida: É uma unidade de capacidade estruturada e reutilizável que instrui o Agent sobre qual SOP seguir para completar uma tarefa específica em um cenário definido.
Vantagens:

  1. Aumenta eficiência incremental

    1. Adicionar chamadas OS API requer apenas prompt, o TRAE gera automaticamente o código;
    2. Para PSMs já importados no OS, SKILL gera todas as chamadas de API necessárias.

  2. Reduz custo de integração

    1. Para um novo PSM, SKILL configura SDK OS, inicializa Client, encapsula QueryWithParams/SqlQuery, tudo automaticamente e dentro do padrão de inicialização.

  3. Evita duplicação e conflitos

    1. SKILL verifica API ID no api_description.md antes de criar, evitando múltiplas implementações do mesmo API e reduzindo deriva lógica.

  4. Padroniza a produção de código

    1. Nomes de métodos, parâmetros de entrada/saída, SQL, logs, tratamento de erros e estilo de comentários são unificados;
    2. Fixação de padrões via examples.md garante aderência à chamada do SDK oficial.

  5. Aumenta manutenibilidade e rastreabilidade

    1. Informações do API ficam centralizadas em api_description.md;
    2. Facilita consultas futuras: o que a API faz, onde é usada, parâmetros.

Convenções de Uso

Para garantir precisão do código gerado pela IA, o SKILL define regras rígidas:

  1. Biblioteca dependente OS: xxx/xxx/sqlclient;

  2. Estrutura de inicialização e arquivos gerados:

    Project Name
└── infra
    └── one_service/
        ├── client.go
        └── get_xxx_xxx.go
    1. infra/one_service/client.go: métodos de inicialização do Client OS;
    2. InitOneService: inicializa Client e fornece SDK;
    3. SqlQuery: encapsula método original SqlQuery com logs;
    4. QueryWithParam: encapsula método original QueryWithParam com logs;
    5. infra/one_service/get_xxx_xxx.go: arquivos de chamadas OS gerados pelo TRAE são armazenados aqui; nomes de arquivos são gerados automaticamente pela IA com base no nome da API.

Começando a Prática

  1. Atualize o TRAE para a versão 3.3.21 ou superior.

  2. Vá em Regras e Skills → Criar Skill.

  1. Faça o upload do arquivo SKILL.md ou de um pacote zip contendo SKILL.md e outros arquivos de configuração

O TRAE atualmente oferece duas formas de upload com um clique para a funcionalidade SKILL:

  • Upload direto do arquivo SKILL.md;

  • Upload de um pacote zip na raiz contendo o SKILL.md, que pode incluir outros diretórios e arquivos de configuração além do SKILL.md.

No final, o arquivo ou pacote zip será armazenado unificadamente em .trae/skills.

  1. Crie uma nova tarefa, insira o Prompt e use o SKILL
// Modo 1: Inserir parâmetros de requisição e retorno, usar QueryWithParam

Preciso gerar um método de chamada OneService API
API ID: xxxxxxxxx
Nome: Consultar métricas de consumo de anúncios offline
Parâmetros de requisição
...
Parâmetros de retorno
...

-----------------------------------------------------------

// Modo 2: Inserir SQL, usar SqlQuery

Preciso gerar um método de chamada OneService API
API ID: xxxxxxxxx
Nome: Consultar métricas de consumo de anúncios offline
SQL: ... (fornecer em bloco de código)
Enter fullscreen mode Exit fullscreen mode

Demonstração de Resultados

OS não inicializado

Teste realizado usando um PSM com OS não inicializado.
Resultado Gerado: Inicialização + Descrição da API + Nova Chamada de API

  • No diretório infra, criar o subdiretório one_service;

  • Importar a biblioteca dependente do OS e adicionar o arquivo client.go com o método de inicialização;

    • Em infra/init.go, chamar o método de inicialização do OS;

  • No diretório infra/one_service, adicionar arquivos contendo os métodos de chamada das APIs necessárias;

  • Em api.description.md, adicionar a descrição da nova API.

OS já inicializado

Teste realizado usando um PSM com OS já inicializado.
Resultado Gerado: Pular Inicialização + Descrição da API + Nova Chamada de API

  • No diretório infra/one_service, adicionar arquivos contendo os métodos de chamada das APIs necessárias;

  • Em api.description.md, adicionar a descrição da nova API.

Ideias de Design do SKILL

Após entender os passos de uso, o ponto mais importante é:

  • Por que este SKILL foi projetado desta forma?

  • Qual é a lógica e a estrutura de composição do SKILL?

A seguir, vamos explicar a lógica central do design desta SKILL a partir de:

  1. Ideias de design

  2. Arquitetura em camadas

  3. Escrita dos arquivos SKILL

Ideias de Design

Estrutura em árvore

.TRAE/
└── SKILLS/
    └── generateosmethod/
        ├── api_description.md
        ├── examples.md
        └── SKIL
Enter fullscreen mode Exit fullscreen mode

Ideia Central
A tarefa de “gerar código de chamada OS API” é dividida em três camadas:

  • Normas / Fluxos

  • Ativos pesquisáveis

  • Templates reutilizáveis

Isso garante que os resultados gerados sejam consistentes, reutilizáveis e gerenciáveis.
1. Usar SKILL.md como “Orquestrador de Fluxos” (restrição forte, evita desvios)

  • SKILL.md define pré-condições (o projeto deve ter importado o SDK, inicializado o Client e fornecido wrappers Query/SqlQuery);

  • Objetivo principal:

    • Evitar reinventar a roda;
    • Evitar gerar chamadas inconsistentes com a estrutura existente do repositório (se o PSM atual já possui infra/oneservice/client.go, o SKILL deve seguir este padrão).

2. Usar api_description.md como “Registro / Índice” (memória e pesquisabilidade)
O api_description.md não é para compilador, mas para “pessoas + ferramentas”, registrando:

  • Cada API ID, seu propósito, SQL, parâmetros de entrada/saída e arquivo Go de destino.

Responsabilidades principais:

  1. Ponto de desduplicação e reutilização

    1. Antes de gerar, pesquisar pelo API ID; evita gerar métodos duplicados;

  2. Acúmulo de conhecimento

    1. Qualquer pessoa pode rapidamente consultar: “o que faz essa API OS, em qual arquivo está, quais parâmetros tem?” sem acessar a plataforma OS ou o código-fonte.

3. Usar examples.md como “Biblioteca de Templates de Código” (uniformizar estilo e postura de chamadas)
examples.md fornece duas práticas padrão:

  • Modo 1: usuário fornece consulta parametrizada, usar QueryWithParams;

  • Modo 2: usuário fornece string SQL, usar SqlQuery.

Durante a geração do código, as importações, logs e agregação de retorno seguem os exemplos, garantindo que todas as chamadas OS no repositório tenham aparência uniforme, reduzindo custos de manutenção.
4. Desacoplamento da estrutura do repositório de negócio

  • O diretório SKILL contém apenas regras e templates, sem código Go de negócio;

  • O código gerado é colocado no diretório infra/oneservice do repositório existente;

  • Objetivo: permitir que o SKILL seja reutilizado em múltiplos projetos, apenas alinhando as pré-condições de inicialização do infra.

SKILL.md

Resumo do conteúdo: define o fluxo e regras do SKILL.

  • Pré-condições: verifica se o serviço atual importou o SDK do OS e inicializou o Client; se não, gera automaticamente;

  • Regras: define quando usar o SKILL e os padrões de geração;

  • Fluxo: define a cadeia de execução do SKILL, núcleo do disclosure progressivo.

---
name: GenerateOSMethod
description: Gera métodos de chamada da API OneService
---
## Pré-requisitos
#### 1. Verifique se o diretório relacionado ao OneService já existe dentro da pasta `infra` do projeto atual, e se o SDK do OneService foi importado e o Client devidamente inicializado.
#### 2. Caso o projeto ainda não possua o SDK do OneService ou o Client não tenha sido inicializado, siga os passos abaixo para realizar a configuração:
- Importe a biblioteca de utilitários do OneService inserindo no terminal: `go get xxx/xxx/sqlclient`
- Crie o diretório `one_service` dentro da pasta `infra` para armazenar o código relacionado, incluindo a inicialização do Client.
- Crie o arquivo `client.go` dentro do diretório `one_service` para inicializar o Client do OneService. Exemplo de código:
```

go
package one_service
import(
"xxx/xxx/sqlclient"
"xxx/xxx/logs"
"xxx/xxx/utils"
"context"
"sync"
)
var Client *sqlclient.SQLClient
var once sync.Once
func InitOneService(){
if Client != nil {
return
    }
    once.Do(func() {
// inicializa o client
       var err error
       Client, err = sqlclient.NewSqlClient()
if err != nil {
          panic(err)
       }
    })
}
func SqlQuery(ctx context.Context, id string, sql string, res interface{}) error {
    err := Client.SqlQuery(ctx, id, sql, res)
if err != nil {
       logs.CtxError(ctx, "[SqlQuery] falha ao executar query sql.id:%s,sql:%s,err:%s", id, sql, err.Error())
return err
    }
return nil
}
func QueryWithParam(ctx context.Context, id string, param map[string]interface{}, res interface{}) error {
    err := Client.QueryWithParams(ctx, id, param, res)
if err != nil {
       logs.CtxError(ctx, "[QueryWithParam] falha ao executar query sql.id:%s,param:%s,err:%s", id, utils.JsonMarshal(ctx, param), err.Error())
return err
    }
return nil
}


```

`

Adicione o método `InitOneService` ao arquivo `init.go` no diretório `infra`, garantindo que o Client seja inicializado na inicialização do projeto.
Se o diretório do OneService já existir na pasta `infra` e o Client já estiver inicializado, verifique a existência dos métodos `SqlQuery` ou `QueryWithParam`. Caso não existam, adicione-os.
**Regras**
Você só deve utilizar a SKILL GenerateOSMethod nas seguintes situações (verificando os pré-requisitos antes):
Quando o usuário mencionar a necessidade de usar ou adicionar uma interface do OneService.
Quando a documentação de fluxo de geração de código ou o documento de solução técnica fornecido pelo usuário indicar a necessidade de usar ou adicionar uma interface do OneService.
Você deve seguir estritamente o \[Fluxo\] definido no arquivo SKILL.md, sem desvios, gerando código apenas nas etapas previstas.
A descrição da API gerada deve seguir o exemplo no arquivo `api_description.md` e ser salva no mesmo.
Crie um novo arquivo `.go` no diretório `infra/one_service` (ou outro diretório existente relacionado ao OneService em `infra`). Todo o código novo (ID da API, método de chamada, instrução SQL, parâmetros de requisição e resposta) deve ser colocado neste novo arquivo, seguindo o exemplo em `examples.md`.
<br>

**Fluxo**

- Verificar se o usuário forneceu o ID da API do OneService


Verifique se o conteúdo inserido pelo usuário ou a documentação indicam explicitamente o ID da API do OneService que deve ser chamado. Se não estiver claro, peça ao usuário para confirmar qual ID de API deve ser utilizado.

- Percorrer os métodos de chamada de API do OneService existentes


Percorra todos os IDs de API definidos no arquivo `api_description.md`. Faça a correspondência pelo ID da API para verificar se já existe um método de chamada para o OneService em questão. Se o usuário fornecer múltiplos IDs, verifique cada um e liste o status de existência para cada ID.

- Confirmar com o usuário a chamada ou adição da interface OneService


Envie a lista com o status de existência dos métodos para os IDs informados e peça a confirmação do usuário:
Se houver correspondência com um método existente, pergunte se ele deseja usá-lo diretamente.
Se não houver correspondência, peça confirmação para criar um novo método.

- Coletar informações da API do OneService


Se o usuário confirmar o uso de um método existente, utilize-o diretamente.
Se o usuário confirmar a criação de um novo método, solicite as informações necessárias: ID da API, instrução SQL, parâmetros de requisição, parâmetros de resposta, etc.

- Gerar código relacionado à API do OneService


Com base nas informações fornecidas, gere o seguinte conteúdo:
Adicione a descrição do novo ID da API no arquivo `api_description.md`, seguindo o modelo do arquivo.
Gere o novo arquivo `.go` no diretório `infra/one_service`, baseando-se no exemplo do arquivo `examples.md`.
O resultado final deve ser a adição da descrição no `api_description.md` e a criação de apenas um novo arquivo `.go` no diretório `infra/one_service` (ou pasta correlata).
<br>

### **examples.md**

**Resumo do conteúdo:**  Templates para geração de conteúdo com SKILL

- **Método 1:**  Template de exemplo usando o método `QueryWithParams`

- **Método 2:**  Template de exemplo usando o método `SqlQuery`


<br>

### **api\_description.md**

**Resumo do conteúdo:**  Documentação das descrições relacionadas às APIs do OS

- **Método 1:**  Nome + ID + arquivo de código gerado + parâmetros de requisição/resposta

- **Método 2:**  Nome + ID + arquivo de código gerado + SQL da requisição + parâmetros de requisição/resposta


<br>

## **Resumo**

O SKILL é aplicável a tarefas que **precisam ser executadas de forma estável**, que envolvem **múltiplos passos** e que possuem um **processo fixo**.
**Destaques do design:**  divulgação progressiva (progressive disclosure), ou seja, equilibrando eficiência de tokens e profundidade funcional por meio de **carregamento em camadas + ativação sob demanda + execução sem contexto**, reduzindo significativamente a pressão sobre o contexto e aumentando a precisão na execução das tarefas.
**Estabilidade:**  não envolve muitos fatores especiais ou cenários de negócio específicos; em 90% dos casos, os processos são relativamente uniformes.
**Múltiplos passos:**  em comparação com conversas passo a passo ou múltiplas rodadas de diálogo, o SKILL permite alcançar o resultado **de forma direta e completa**.
**Processo fixo:**  o agente segue os steps definidos no `SKILL.md` de forma sequencial. Diferente de diálogos comuns, a IA não faz associações livres nem varreduras contextuais, evitando:

- Consumo excessivo de recursos devido a contextos extensos;

- Maior probabilidade de “alucinações” do modelo, prevenindo respostas erradas ou códigos gerados de forma incorreta.


Vale destacar que os exemplos do artigo combinam ferramentas internas da empresa, e suas configurações **não podem ser reutilizadas diretamente**. O ponto central do texto, como indicado no título, é **compartilhar a lógica de design do SKILL**, oferecendo inspiração para os leitores.
Qualquer tarefa que seja **executada de forma estável**, contenha **múltiplos passos** e tenha **processo fixo** pode ser abstraída como um **SOP (Procedimento Operacional Padrão) claro** e consolidada via SKILL, permitindo que agentes inteligentes executem de forma estável e eficiente.
Seguindo a linha principal: **“primeiro organizar o processo, depois abstrair de forma estruturada, e então deixar a ferramenta executar”**, é possível construir continuamente capacidades de automação para indivíduos, equipes e empresas, **não se limitando apenas aos exemplos apresentados**.
O futuro da programação com IA é incerto, ninguém sabe ao certo como será. Mas uma coisa é certa: **quem começar a aprender com seriedade, praticar ativamente e compreender profundamente, terá mais capacidade de moldar e se adaptar a esse futuro**.
Experimente, falhe, aprenda. **O próprio processo é o valor.** 
<br>
Enter fullscreen mode Exit fullscreen mode

Top comments (0)