A Proposta .well-known para Agent Skills

Visão Geral

Um arquivo markdown com frontmatter YAML está se tornando a forma padrão de estender agentes de IA. O SKILL.md define o que um skill faz, quando deve ser ativado e quais instruções o agente deve seguir.

A Anthropic publicou a especificação em dezembro de 2025 e, em poucos meses, ela foi adotada por mais de 30 produtos de agentes, incluindo Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Cursor e VS Code. Independentemente do que aconteça com registries e descoberta, o SKILL.md é o formato de fato.

O formato está consolidado. As perguntas em aberto são sobre distribuição e descoberta: como os skills são empacotados, instalados e encontrados?

Um sistema de distribuição e uma proposta de descoberta se destacam:

1. Claude Code Plugin Marketplace: um sistema federado para distribuir extensões multicomponente (skills, hooks, agentes e tool servers). É específico do Claude Code, mas outros agentes de codificação (Codex, Cursor, Copilot, Gemini CLI) consomem os mesmos arquivos SKILL.md com pequenas variações nos nomes das pastas.
2. Agent Skills Discovery: a RFC da Cloudflare propondo publicação descentralizada de skills via URIs .well-known.

Neste post percorro o formato SKILL.md, o Plugin Marketplace, a proposta .well-known e faço instalações práticas com exemplos concretos, depois descrevo quando usar cada ferramenta.

As Três Camadas dos Agent Skills

O ecossistema está se organizando em três camadas distintas:

O Formato SKILL.md

Entender o padrão aberto SKILL.md é fundamental para trabalhar com qualquer parte desse ecossistema. Todo sistema de distribuição e descoberta é construído sobre ele.

Um skill é um diretório contendo um arquivo SKILL.md com frontmatter YAML e instruções em markdown:

my-skill/
├── SKILL.md           # Main instructions (required)
├── scripts/           # Optional executables
├── references/        # Optional documentation
└── assets/            # Optional templates/resources

O frontmatter é minimalista. Apenas name e description são obrigatórios; a especificação também define campos opcionais license, compatibility, metadata e allowed-tools:

---
name: deploy-to-production
description: Deploy the application to production following the team's release checklist.
  Use when the user asks to "deploy", "ship", "release", or "push to prod".
---

## Pre-flight checks
1. Run the full test suite
2. Check that the changelog is updated
3. Verify no breaking API changes

## Deployment steps
1. Build the production bundle
2. Run database migrations
3. Deploy to staging first, verify
4. Promote to production
5. Run smoke tests against production

## Rollback procedure
If smoke tests fail, immediately run the rollback script...

O modelo de divulgação progressiva mantém o custo de contexto baixo. Na inicialização, os agentes carregam apenas name + description (cerca de 100 tokens por skill). O corpo completo do SKILL.md só carrega quando uma tarefa corresponde, e arquivos de suporte só carregam quando referenciados. Isso significa que você pode ter dezenas de skills instalados sem inflar a janela de contexto.

O Claude Code estende o padrão com campos adicionais no frontmatter, agrupados em três temas:

• Controle de invocação (disable-model-invocation, user-invocable, when_to_use): decide quem pode acionar o skill e como o Claude o correlaciona com requisições
• Controle de execução (context: fork, agent, model, effort): executa o skill em um subagente isolado com um modelo específico e nível de esforço de raciocínio
• Ativação e ciclo de vida (paths, hooks, argument-hint): ativação automática com escopo por glob, hooks de ciclo de vida e dicas de autocompletar para argumentos

Claude Code Plugin Marketplace

O sistema de plugins do Claude Code resolve o problema de distribuição para extensões completas e multicomponente que empacotam skills, agentes, hooks, tool servers e LSP servers em um único package instalável. O empacotamento de plugin é específico do Claude Code, mas os skills dentro de cada plugin são portáteis: outros agentes de codificação leem o mesmo formato SKILL.md com apenas pequenas diferenças nos nomes das pastas. O Claude Code procura em .claude/skills/, o Codex procura em .agents/skills/, e Cursor, Copilot e Gemini CLI seguem convenções similares.

Arquitetura

Um plugin marketplace é um repository Git contendo um arquivo marketplace.json que lista os plugins disponíveis. Cada entrada de plugin aponta para uma origem (repo do GitHub, URL de Git, caminho local ou package npm) e pode fixar um commit SHA específico para reprodutibilidade. O marketplace oficial da Anthropic já vem embutido no Claude Code.

Um marketplace.json se parece com isto:

{
  "name": "team-tools",
  "owner": {
    "name": "DevTools Team"
  },
  "plugins": [
    {
      "name": "cloudflare",
      "description": "Skills for building on Cloudflare Workers, Agents SDK, and more",
      "source": {
        "source": "github",
        "repo": "cloudflare/skills"
      }
    },
    {
      "name": "local-conventions",
      "description": "Team coding conventions and deployment checklist",
      "source": "./plugins/local-conventions"
    }
  ]
}

O Que Torna os Plugins Diferentes

Plugins são a abordagem mais verticalmente integrada. Um único plugin pode conter:

• Skills (arquivos SKILL.md com instruções para o agente)
• Agentes (definições de subagentes para tarefas especializadas)
• Hooks (comandos shell que executam automaticamente em eventos)
• MCP servers (conexões externas com tools e fontes de dados via .mcp.json)
• LSP servers (inteligência de linguagem para mais de 11 linguagens via .lsp.json)
• Monitors (processos em background que fazem tail de logs ou observam arquivos e transmitem eventos ao Claude como notificações)
• Executáveis (um diretório bin/ adicionado ao PATH da Bash tool enquanto o plugin estiver ativo)
• Configurações padrão (um settings.json que pode, por exemplo, ativar um dos agentes customizados do plugin como thread principal)

Esse empacotamento é poderoso. O plugin da Cloudflare, por exemplo, entrega 8 skills especializados junto com tool servers para acesso a documentação ao vivo, exploração de API, consultas de observabilidade e gerenciamento de build. Instalá-lo dá ao Claude Code expertise profunda em Cloudflare em um único comando.

O tradeoff é a portabilidade: o empacotamento de plugin, os hooks e os metadados do marketplace funcionam principalmente com Coding Agents. Embora seja conveniente aproveitar os registries do GitHub e do NPM para hospedar os plugins/skills, essa pode não ser a melhor escolha para outros agentes.

Agent Skills Discovery: A Proposta .well-known

A RFC Cloudflare Agent Skills Discovery adota uma abordagem fundamentalmente diferente para a questão da distribuição. Em vez de um catálogo hospedado em Git ou de um gerenciador de packages, ela propõe que qualquer domínio possa publicar skills descobríveis em uma URL previsível, seguindo a RFC 8615 (o mesmo padrão por trás de /.well-known/openid-configuration e dos desafios de certificados ACME).

O ecossistema de IA já usa esse padrão em outros lugares: o protocolo A2A publica agent cards em /.well-known/agent-card.json para anunciar a identidade do agente, capabilities, skills e requisitos de autenticação, e o agent-skills-discovery é o análogo no nível de skill.

Como Funciona

Uma organização publica um index.json em:

https://example.com/.well-known/agent-skills/index.json

O índice lista os skills disponíveis com nomes, descrições, tipos, URLs e digests SHA-256 para verificação de integridade:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "deploy-to-workers",
      "description": "Deploy applications to Cloudflare Workers with best practices for routing, bindings, and environment configuration",
      "type": "skill-md",
      "url": "./skills/deploy-to-workers/SKILL.md",
      "digest": "sha256:a1b2c3d4e5f6..."
    },
    {
      "name": "durable-objects",
      "description": "Build stateful coordination with Durable Objects including RPC methods, SQL storage, and WebSocket hibernation",
      "type": "archive",
      "url": "./skills/durable-objects.tar.gz",
      "digest": "sha256:f6e5d4c3b2a1..."
    }
  ]
}

O type de cada entrada informa ao agente como buscar o skill. skill-md aponta para um único arquivo SKILL.md, bom para skills que contêm apenas instruções. archive aponta para um bundle .tar.gz ou .zip contendo o SKILL.md além de scripts/, references/ e assets de suporte; o agente verifica o digest SHA-256, descompacta localmente e carrega os recursos sob demanda.

A especificação usa divulgação progressiva em três níveis:

1. Nível 1 (Índice): o agente busca o index.json para ver os skills disponíveis. Cada entrada usa cerca de 100 tokens de contexto.
2. Nível 2 (Instruções): quando um skill corresponde a uma tarefa, o agente busca o SKILL.md completo (recomendado abaixo de 5K tokens).
3. Nível 3 (Recursos): arquivos de suporte (scripts, referências, assets) carregam sob demanda de archives descompactados.

Por Que os Desenvolvedores Gostam

O apelo é a simplicidade.

A RFC é construída inteiramente sobre infraestrutura web existente: HTTP, JSON, digests SHA-256, resolução de URL da RFC 3986. Sem protocolo novo, sem runtime novo, sem esquema de autenticação novo. Se você consegue servir arquivos estáticos, você consegue publicar agent skills.

Estado Atual

A RFC está na v0.2.0 (draft, atualizada em 12 de março de 2026). A versão 0.2.0 introduziu mudanças quebradoras em relação à v0.1.0: o URI foi renomeado de /.well-known/skills/ para /.well-known/agent-skills/, o campo de versão foi substituído por um URI $schema e a verificação de digest SHA-256 foi adicionada. O repo acompanha issues e atualizações do schema.

A comunidade está no processo de adotar a RFC da Cloudflare dentro da especificação Agent Skills. Existe um PR aberto acompanhando isso.

A Vercel Skills CLI é a forma mais fácil de instalar skills. Ela detecta automaticamente quais agentes você tem instalados e grava cada skill na pasta correta para cada um: .claude/skills/ para Claude Code, .agents/skills/ para Codex e equivalentes para mais de 45 agentes suportados. Instalar skills a partir de uma localização .well-known é suportado, embora ainda não esteja documentado [PRECISA VERIFICAÇÃO].

Testando: Instalando Skills a partir de /.well-known/agent-skills/

Para tornar isso concreto, publiquei dois pequenos skills de validação para o my2cents.ai no caminho compatível com a especificação. O índice de descoberta fica em https://www.my2cents.ai/.well-known/agent-skills/index.json e anuncia:

• my2cents-hello: imprime uma linha de assinatura fixa para que eu possa confirmar que a descoberta e a instalação funcionaram de ponta a ponta.
• my2cents-about: retorna uma descrição pronta de um parágrafo sobre o blog.

Toda a minha configuração são três arquivos estáticos servidos no caminho well-known:

/.well-known/
└── agent-skills/
    ├── index.json                      # Discovery index with SHA-256 digests
    └── skills/
        ├── my2cents-hello/SKILL.md
        └── my2cents-about/SKILL.md

O próprio index.json tem poucas linhas, seguindo o schema da RFC v0.2.0:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "my2cents-hello",
      "description": "A tiny validation skill that prints a fixed signature line so you can confirm skill discovery and installation worked end-to-end.",
      "type": "skill-md",
      "url": ".well-known/agent-skills/skills/my2cents-hello/SKILL.md",
      "digest": "sha256:f53e6e60c2ead..."
    },
    {
      "name": "my2cents-about",
      "description": "Returns a canned one-paragraph description of my2cents.ai verbatim.",
      "type": "skill-md",
      "url": ".well-known/agent-skills/skills/my2cents-about/SKILL.md",
      "digest": "sha256:3fecbcc253f14..."
    }
  ]
}

Eu os instalei com a Vercel Skills CLI. Instale a CLI uma vez e um comando basta para baixar os skills:

npm install -g skills
skills add https://www.my2cents.ai

(Se preferir não instalar globalmente, npx skills add https://www.my2cents.ai também funciona.)

Por baixo dos panos, o skills add faz quatro coisas:

1. Resolve o caminho de descoberta. Dado um domínio simples, a CLI anexa /.well-known/agent-skills/index.json e faz o fetch. Não precisei passar o caminho completo.
2. Lê o índice. Ela faz parse do array skills e mostra o nome e a descrição de cada skill para que eu possa escolher quais instalar (ou instalar todos).
3. Verifica a integridade. Para cada entrada com digest, baixa o SKILL.md (ou archive), calcula o SHA-256 e aborta se o digest não bate com o índice.
4. Grava na pasta correta por agente. A CLI escaneia o projeto atual em busca de marcadores de agentes (.claude/, .agents/, .cursor/, etc.) e copia cada skill para o diretório correspondente. Como eu uso o Claude Code, meus skills foram parar em .claude/skills/my2cents-hello/SKILL.md e .claude/skills/my2cents-about/SKILL.md.

Alguns outros subcomandos do skills que vale conhecer:

skills list                    # show installed skills
skills find <query>            # search the skills.sh directory
skills update                  # re-fetch and re-verify all installed skills
skills rm my2cents-hello       # uninstall a skill

Depois validei no Claude Code:

/my2cents-hello
# → 👋 Hello from my2cents.ai — my2cents-hello skill v1 is loaded.

/my2cents-about
# → my2cents.ai is an AI-focused technical blog with daily AI news roundups...

Essa foi toda a história de publicação para mim: um arquivo JSON estático em um caminho previsível, digests SHA-256 para integridade, e qualquer agente do outro lado consegue encontrar e instalar os skills. Sem conta em registry, sem etapa de publish de package, sem auth.

Veredito

Pelo que vi, o cenário de agent skills está convergindo para um conjunto compartilhado de primitivas. SKILL.md é o formato. Divulgação progressiva é o padrão de carregamento. As perguntas em aberto são sobre distribuição e descoberta.

Claude Code Plugin Marketplace é, na minha visão, o sistema de distribuição mais capaz disponível hoje. A capacidade de empacotar skills, hooks, agentes, tool servers e LSP servers em um único package instalável é genuinamente útil. O tradeoff é o lock-in com Claude Code: os skills em si são portáteis para Codex, Cursor, Copilot e Gemini CLI via o formato SKILL.md compartilhado, mas o empacotamento do plugin não é. Se você trabalha principalmente no Claude Code e quer a integração mais profunda, é por aqui.

Agent Skills Discovery (.well-known) é a proposta mais arquiteturalmente sólida que analisei. Construir sobre a RFC 8615 significa que não há nova infraestrutura, nenhum ponto central de falha, e qualquer domínio pode participar. Ainda é um draft, e a adoção além da Mintlify é limitada, mas o design está certo. Se você é fornecedor de plataforma ou provedor de documentação, publicar em /.well-known/agent-skills/ é um investimento de baixo custo com potencial para alcance amplo. Publicar o meu foram três arquivos estáticos, como mostrei acima.

A maior lacuna que vejo é a busca multiplataforma. Nenhuma ferramenta busca em todos os diretórios de skills simultaneamente. A Agentic AI Foundation pode consolidar esses esforços eventualmente, embora eu não apostaria em um cronograma.

Por ora, minha abordagem prática é usar SKILL.md como formato, plugins do Claude Code (ou a pasta de skills equivalente no seu agente de escolha) quando precisar de integração profunda, npx skills para instalar entre agentes e ficar de olho em .well-known/agent-skills/ conforme a camada de descoberta amadurece. As peças estão todas na mesa. Conectá-las é o trabalho que vem pela frente.