Gerenciar Skills do Tracecat

O que Gerenciar Skills do Tracecat faz?

O Tracecat MCP fornece seis ferramentas de skill: list_skills, get_skill, prepare_skill_download, prepare_skill_upload, complete_skill_upload e publish_skill.

As gravações são em etapas, não inline. Bytes de arquivo nunca viajam como argumentos de ferramenta: prepare_skill_upload recebe apenas metadados — caminho, SHA-256, tamanho, tipo de conteúdo — e retorna uma URL PUT de curta duração por arquivo; os bytes vão para essas URLs via HTTP simples; complete_skill_upload então anexa os blobs em etapas e substitui o rascunho. Não procure por um argumento content_base64 inline e nunca leia bytes de arquivo no contexto para enviá-los.

O helper incluído remove as partes que são propensas a erros quando feitas manualmente: a varredura segura de diretórios, rejeição de links simbólicos, aplicação do SKILL.md raiz e os digests SHA-256.

Enviar uma skill

Os mesmos quatro passos criam uma skill e substituem uma existente. A única diferença é quais argumentos de identidade prepare_skill_upload recebe.

1. Resolva o workspace alvo com list_workspaces, depois chame list_skills. Para uma skill nova, confirme que o nome está livre — omitir skill_id sempre cria uma nova linha, então uma segunda criação resulta em duas skills com o mesmo name e slugs diferentes. Para uma skill existente, pegue seu skill_id.

2. Construa o array de metadados:

   python3 <this-skill-dir>/scripts/upload_skill_files.py metadata <local-skill-dir>
   

   Ele imprime o array files literalmente: uma entrada por arquivo com path, sha256, size_bytes e content_type. Nenhum conteúdo de arquivo.

3. Chame prepare_skill_upload com workspace_id e o array files, mais:

   • name (e description opcional) e sem skill_id, para criar uma skill; ou
   • skill_id e sem name/description, para substituir o rascunho de uma skill existente.

   Para uma criação, passe o mesmo name que o frontmatter local declara — o servidor mescla name e description no frontmatter SKILL.md raiz armazenado antes de validar, então um argumento incompatível reescreve silenciosamente o que é armazenado.

   A resposta carrega skill_id, base_revision, created, e por arquivo: upload_id, upload_url, method, headers e expires_at.

4. Faça PUT dos bytes brutos de cada arquivo para sua upload_url com o método e cabeçalhos retornados, diretamente do disco. As URLs são de curta duração; verifique expires_at e re-prepare em vez de tentar novamente uma URL obsoleta.

5. Chame complete_skill_upload com workspace_id, skill_id, o base_revision do passo 3 e um array files de {"path": ..., "upload_id": ...} para cada arquivo. Isso substitui o rascunho e não publica.

6. Chame publish_skill com o skill_id quando a skill deve ser anexável a presets. Um rascunho não publicado não pode ser vinculado.

base_revision é uma proteção de concorrência. Um draft_revision_conflict significa que outra pessoa editou o rascunho desde o passo 3 — chame get_skill para ver a draft_revision atual e o que uma substituição completa removeria, depois re-prepare.

Atualizando uma skill em uso

Uma correção que para após complete_skill_upload não altera nada que qualquer agente execute. Três passos, em ordem:

1. prepare_skill_upload com skill_id → PUT os bytes → complete_skill_upload. Isso substitui o rascunho. Não publica.
2. publish_skill com o mesmo skill_id. Skills são versionadas; isso cria uma nova versão imutável e move o current_version_id da skill.
3. update_agent_preset com a lista skills do preset consumidor — as mesmas entradas {"skill_id": ...} que já tinha. Cada vinculação é re-fixada na versão publicada atual da skill no momento da gravação, então um preset vinculado antes do passo 2 continua executando a versão antiga até que esta chamada a reescreva.

Pular o passo 3 é a falha clássica: a nova versão existe, o preset nunca a vê.

Verifique re-obtendo. get_skill sem path retorna o manifesto do rascunho — caminhos, digests, tamanhos, draft_revision, is_publishable, validation_errors — e nunca conteúdos de arquivo; get_skill com path lê um arquivo, inline quando é texto UTF-8 pequeno. list_skills mostra o current_version_id da skill; get_agent_preset mostra skills[].skill_version_id e skills[].skill_version. Confirme que ambos mudaram.

Isso é trabalho rotineiro e reversível. Toda versão publicada é imutável e ainda vinculável, então uma má publicação é desfeita publicando uma árvore corrigida e religando. Faça isso em vez de narrar riscos; reserve cautela para operações que realmente não podem ser desfeitas.

Declarando as ferramentas da skill

Uma skill carrega suas próprias ferramentas. Declare-as no frontmatter do SKILL.md raiz em metadata.tools, como nomes de ação de registro ou entradas mcp.<slug> / mcp.<slug>.<tool>, até 64 por skill:

---
name: slack-triage
description: Postar e atualizar triagem de threads no Slack.
metadata:
  tools:
    - tools.slack.post_message
    - tools.slack.list_replies
---

Todo preset ao qual a skill está anexada recebe essas ferramentas além de sua própria lista de permissões actions. Elas são concedidas assim que o preset é resolvido, quer o modelo abra ou não a skill; apenas as instruções da skill são carregadas sob demanda.

Prefira isso a listar as mesmas ferramentas em actions de cada preset quando as ferramentas se agrupam naturalmente e vários agentes as reutilizam — uma edição e uma republicação então atualizam todos os presets consumidores. Mantenha uma ferramenta em actions do preset quando ela é específica para aquele agente.

Uma ressalva: o filtro namespaces de um preset se aplica às ferramentas de registro na união e bloqueia silenciosamente aquelas fora dele. Após anexar uma skill a um preset com restrição de namespace, verifique tool_policy.blocked_tools em get_agent_preset. Ferramentas MCP que uma skill declara (mcp.<slug> / mcp.<slug>.<tool>) não são filtradas por namespaces e não aparecem lá.

Alterar metadata.tools muda o que os agentes podem executar, então segue os mesmos três passos que qualquer outra correção: substituir o rascunho, publish_skill e depois update_agent_preset para re-fixar o vínculo. Uma leitura do preset resultante mostra as ferramentas concedidas como uma única lista plana em tool_policy.actions, sem proveniência por skill — a união é o que você pode verificar.

Tamanho

Bytes não passam mais pelo contexto do modelo, mas cada arquivo ainda tem um limite de tamanho no servidor e uma árvore inteira ainda é mais fácil de revisar quando é pequena e apenas texto.

• Prefira Markdown, YAML e scripts. Hospede um grande ativo binário em outro lugar e faça referência a ele.
• Mova detalhes longos para arquivos references/ que o agente lê sob demanda em vez de para SKILL.md.
• Se uma árvore for grande demais para raciocinar, divida a própria skill em duas skills. Não divida uma árvore entre várias chamadas complete_skill_upload — cada chamada substitui o rascunho inteiro, então uma chamada parcial exclui tudo o que omite.

Regras rígidas

• Omitir skill_id cria; passá-lo substitui. Nunca crie contra um nome que já existe — a repetição do slug faz com que a duplicata tenha sucesso em vez de falhar.
• Toda gravação substitui o rascunho inteiro. Arquivos ausentes do diretório local são excluídos da skill. Sempre envie a árvore completa.
• Faça upload de cada arquivo preparado antes de chamar complete_skill_upload e passe cada caminho de volta com seu upload_id.
• Nunca coloque bytes de arquivo ou base64 inline em um argumento de ferramenta e nunca leia os bytes de uma URL de upload ou download no contexto. Faça streaming de e para o disco.
• Publicar não move os vínculos de preset existentes. Reescreva a lista skills do preset para pegar uma nova versão.
• Rejeite arquivos e diretórios com links simbólicos e nunca envie conteúdo de fora da raiz da skill selecionada. O helper aplica isso; não o contorne.
• O arquivo raiz deve ser exatamente SKILL.md, no nível superior, e UTF-8 válido. O servidor rejeita um conjunto de arquivos sem ele.
• Se o cliente não puder executar scripts locais, diga isso e dê ao usuário o comando helper para executar. Não substitua digests gerados pelo modelo.

Referências

• Leia references/upload-contract.md para as formas literais de requisição e resposta e o que este caminho protege e não protege.
• Leia references/troubleshooting.md quando um upload, publicação ou religação de preset não for efetivado.