zurats/agent-skills-discovery-rfc

O que agent-skills-discovery-rfc faz?

🕵️♂️ Descubra habilidades de agente facilmente usando URIs bem conhecidas para simplificar o acesso e a implementação em diversas plataformas e recursos.

Visão Geral

Este skill implementa um mecanismo de descoberta padronizado para habilidades de agente de IA, baseado no conceito de URIs bem conhecidas (well-known URIs) definido na RFC 8615. Ele permite que agentes (como Claude Code, Cursor, Codex, etc.) anunciem suas capacidades de forma dinâmica e que ferramentas e outros agentes as descubram automaticamente.

Como Funciona

1. Um agente ou projeto hospeda um arquivo JSON no caminho /.well-known/agent-skills em seu domínio.
2. O arquivo lista as habilidades disponíveis, cada uma com:
   • name: Nome da habilidade
   • description: Descrição curta
   • version: Versão da habilidade
   • platforms: Lista de plataformas compatíveis (ex: claude-code, cursor, codex)
   • uri: URI para acessar a definição completa da habilidade (ex: URL de um arquivo SKILL.md)
3. Ferramentas de descoberta (como CLI ou bibliotecas) consultam https://<domínio>/.well-known/agent-skills para obter a lista.
4. O skill pode ser usado tanto para anunciar quanto para consumir habilidades.

Exemplo de Arquivo .well-known/agent-skills

{
  "skills": [
    {
      "name": "code-review",
      "description": "Realiza revisão de código automatizada",
      "version": "1.0.0",
      "platforms": ["claude-code", "cursor"],
      "uri": "https://example.com/skills/code-review/SKILL.md"
    },
    {
      "name": "deploy",
      "description": "Implanta aplicações em ambientes cloud",
      "version": "2.1.0",
      "platforms": ["codex"],
      "uri": "https://example.com/skills/deploy/SKILL.md"
    }
  ]
}

Uso

Para anunciar habilidades

1. Crie o arquivo /.well-known/agent-skills no diretório raiz do seu servidor web ou projeto.
2. Inclua as habilidades no formato JSON acima.
3. Certifique-se de que o servidor web sirva o arquivo com o tipo MIME application/json.

Para consumir habilidades

1. Use uma ferramenta que suporte este skill ou implemente uma chamada HTTP para https://<domínio>/.well-known/agent-skills.
2. Parseie o JSON retornado para obter a lista de habilidades.
3. Para cada habilidade, baixe o SKILL.md correspondente da URI fornecida.

Plataformas Suportadas

• Claude Code
• Cursor
• Codex
• Qualquer agente ou ferramenta que suporte URIs bem conhecidas

Considerações de Implementação

• O caminho /.well-known/agent-skills segue o padrão RFC 8615 para URIs bem conhecidas.
• O arquivo deve ser servido com cabeçalho Content-Type: application/json.
• O cache pode ser implementado pelo cliente para evitar consultas frequentes.
• Habilidades podem ser versionadas para compatibilidade retroativa.