Referência da API

Skills

Publique pacotes versionados de conhecimento e arquivos usados por agents.

#Endpoints

Método	Caminho	Descrição
POST	`/v1/skills`	Cria a skill com a primeira versão.
POST	`/v1/skills/:id`	Publica nova versão.
POST	`/v1/skills/:id/archive`	Arquiva a skill.
GET	`/v1/skills`	Lista skills por cursor e filtro de nome.
GET	`/v1/skills/:id/versions`	Lista versões.
GET	`/v1/skills/:id/content`	Versão inteira com o conteúdo dos arquivos.
GET	`/v1/skills/:id/files/*path`	Obtém arquivo da skill.
GET	`/v1/skills/:id`	Lê manifest e arquivos de uma versão.

#Publicar

json

{
  "manifest": {
    "name": "sinistros-auto",
    "description": "Procedimento para análise inicial de sinistros auto",
    "entry": "SKILL.md"
  },
  "files": [
    {
      "path": "SKILL.md",
      "content": "# Sinistros auto\n\nSiga o checklist antes de concluir."
    }
  ]
}

O manifesto pode ser derivado do SKILL.md quando você envia uma pasta compatível.

#Versões

Para publicar uma nova versão, envie o conteúdo atualizado e a versão atual esperada.

json

{
  "version": 1,
  "files": [{ "path": "SKILL.md", "content": "# Sinistros auto\n\nNovo procedimento." }]
}

version é a versão atual que você espera substituir — não o número novo. Se outra pessoa publicou no meio, a resposta é 409 skill.version_conflict e nada é gravado; releia a versão e reenvie.

#Ler a versão inteira (para editar)

http

GET /v1/skills/:id/content?version=3

Devolve o manifesto e todos os arquivos com o texto embutido — diferente de GET :id, que traz só as referências, e de files/*path, que devolve uma URL assinada por arquivo.

json

{
  "skillId": "skill_...",
  "name": "sinistros-auto",
  "version": 3,
  "currentVersion": 3,
  "manifest": { "name": "sinistros-auto", "description": "...", "entry": "SKILL.md" },
  "files": [
    {
      "path": "SKILL.md",
      "contentType": "text/markdown; charset=utf-8",
      "bytes": 48,
      "content": "# Sinistros auto\n\nSiga o checklist."
    }
  ]
}

files tem o mesmo formato aceito na publicação, então ler → editar → publicar é o mesmo objeto do começo ao fim. Isso é necessário porque versões são imutáveis: publicar é enviar o conjunto COMPLETO, inclusive os arquivos que você não mudou. currentVersion diz se version é a cabeça ou uma versão antiga.

No SDK: await client.skills.content('skill_...', { version: 3 }).