DataShrimp/skills

Origem da Fonte

• Repositório Oficial: anthropics/skills — mcp-builder/SKILL.md
• Referências Adicionais de Engenharia de Skill Incluídas:
  • Claude Code Skills — Injeção de Contexto Dinâmica (!comando``)
  • OpenAI ChatGPT & Codex Skills (agents/openai.yaml)
  • Especificação de Skills para Agentes — Script Harness (agentskills.io)

---

Parte 1: Exemplar Oficial do Anthropic mcp-builder/SKILL.md (Divulgação Progressiva em 3 Níveis)

Visão Geral

Crie servidores MCP (Model Context Protocol) que permitem que LLMs interajam com serviços externos através de ferramentas bem projetadas. A qualidade de um servidor MCP é medida pela sua capacidade de permitir que LLMs realizem tarefas do mundo real.

---

Processo

🚀 Fluxo de Trabalho de Alto Nível

Criar um servidor MCP de alta qualidade envolve quatro fases principais:

Fase 1: Pesquisa e Planejamento Aprofundados

1.1 Entender o Design Moderno de MCP

Cobertura de API vs. Ferramentas de Fluxo de Trabalho: Equilibre a cobertura abrangente de endpoints de API com ferramentas de fluxo de trabalho especializadas. Ferramentas de fluxo de trabalho podem ser mais convenientes para tarefas específicas, enquanto a cobertura abrangente dá aos agentes flexibilidade para compor operações. O desempenho varia por cliente — alguns clientes se beneficiam da execução de código que combina ferramentas básicas, enquanto outros funcionam melhor com fluxos de trabalho de nível superior. Quando estiver em dúvida, priorize a cobertura abrangente de API.

Nomeação e Descoberta de Ferramentas: Nomes de ferramentas claros e descritivos ajudam os agentes a encontrar as ferramentas certas rapidamente. Use prefixos consistentes (por exemplo, github_create_issue, github_list_repos) e nomeação orientada a ação.

Gerenciamento de Contexto: Os agentes se beneficiam de descrições concisas de ferramentas e da capacidade de filtrar/paginar resultados. Projete ferramentas que retornem dados focados e relevantes. Alguns clientes suportam execução de código, o que pode ajudar os agentes a filtrar e processar dados de forma eficiente.

Mensagens de Erro Acionáveis: As mensagens de erro devem guiar os agentes em direção a soluções com sugestões específicas e próximos passos.

1.2 Estudar a Documentação do Protocolo MCP

Navegue pela especificação MCP: Comece com o mapa do site para encontrar páginas relevantes: https://modelcontextprotocol.io/sitemap.xml Em seguida, busque páginas específicas com o sufixo .md para o formato markdown (por exemplo, https://modelcontextprotocol.io/specification/draft.md).

Principais páginas para revisar:

• Visão geral da especificação e arquitetura
• Mecanismos de transporte (HTTP streamable, stdio)
• Definições de ferramenta, recurso e prompt

1.3 Estudar a Documentação do Framework

Stack Recomendado:

• Linguagem: TypeScript (suporte SDK de alta qualidade e boa compatibilidade em muitos ambientes de execução, ex. MCPB. Além disso, modelos de IA são bons em gerar código TypeScript, beneficiando-se de seu uso amplo, tipagem estática e boas ferramentas de linting)
• Transporte: HTTP Streamable para servidores remotos, usando JSON sem estado (mais simples de escalar e manter, em oposição a sessões com estado e respostas em streaming). stdio para servidores locais.

Carregue a documentação do framework:

• Práticas Recomendadas de MCP: 📋 Ver Práticas Recomendadas - Diretrizes principais para todos os servidores MCP
• Para TypeScript (recomendado): ⚡ Guia TypeScript - Padrões e exemplos TypeScript
• Para Python: 🐍 Guia Python - Padrões e exemplos Python/FastMCP

1.4 Planeje sua Implementação

Entenda a API: Revise a documentação da API do serviço para identificar endpoints-chave, requisitos de autenticação e modelos de dados. Use pesquisa na web e busca na web conforme necessário.

Seleção de Ferramentas: Priorize a cobertura abrangente de API. Liste os endpoints a serem implementados, começando pelas operações mais comuns.

---

Fase 2: Implementação

2.1 Configurar Estrutura do Projeto

Consulte os guias específicos de linguagem para configuração do projeto:

• ⚡ Guia TypeScript - Estrutura do projeto, package.json, tsconfig.json
• 🐍 Guia Python - Organização de módulos, dependências

2.2 Implementar Infraestrutura Principal

Crie utilitários compartilhados:

• Cliente de API com autenticação
• Auxiliares de tratamento de erro
• Formatação de resposta (JSON e Markdown)
• Suporte a paginação

2.3 Implementar Ferramentas

Para cada ferramenta:

Esquema de Entrada:

• Use Zod (TypeScript) ou Pydantic (Python)
• Inclua restrições e descrições claras
• Adicione exemplos nas descrições dos campos

Esquema de Saída:

• Defina outputSchema quando possível para dados estruturados
• Use structuredContent nas respostas da ferramenta (recurso do SDK TypeScript)
• Ajuda os clientes a entender e processar as saídas da ferramenta

Descrição da Ferramenta:

• Resumo conciso da funcionalidade
• Descrições dos parâmetros
• Esquema do valor de retorno

Implementação:

• Async/await para operações de E/S
• Tratamento de erro adequado com mensagens acionáveis
• Suporte a paginação quando aplicável
• Retorne tanto conteúdo de texto quanto dados estruturados ao usar SDKs modernos

Anotações:

• readOnlyHint: verdadeiro/falso
• destructiveHint: verdadeiro/falso
• idempotentHint: verdadeiro/falso
• openWorldHint: verdadeiro/falso

---

Fase 3: Revisão e Teste

3.1 Qualidade do Código

Revise quanto a:

• Nenhum código duplicado (princípio DRY)
• Tratamento de erro consistente
• Cobertura total de tipos
• Descrições de ferramentas claras

3.2 Compilar e Testar

TypeScript:

• Execute npm run build para verificar a compilação
• Teste com MCP Inspector: npx @modelcontextprotocol/inspector

Python:

• Verifique a sintaxe: python -m py_compile seu_servidor.py
• Teste com MCP Inspector

Consulte os guias específicos de linguagem para abordagens de teste detalhadas e listas de verificação de qualidade.

---

Fase 4: Criar Avaliações

Após implementar seu servidor MCP, crie avaliações abrangentes para testar sua eficácia.

Carregue ✅ Guia de Avaliação para diretrizes completas de avaliação.

4.1 Entender o Propósito da Avaliação

Use avaliações para testar se LLMs podem usar efetivamente seu servidor MCP para responder a perguntas realistas e complexas.

4.2 Criar 10 Perguntas de Avaliação

Para criar avaliações eficazes, siga o processo descrito no guia de avaliação:

1. Inspeção de Ferramentas: Liste as ferramentas disponíveis e entenda suas capacidades
2. Exploração de Conteúdo: Use operações SOMENTE LEITURA para explorar os dados disponíveis
3. Geração de Perguntas: Crie 10 perguntas complexas e realistas
4. Verificação de Respostas: Resolva cada pergunta você mesmo para verificar as respostas

4.3 Requisitos de Avaliação

Garanta que cada pergunta seja:

• Independente: Não dependente de outras perguntas
• Somente leitura: Apenas operações não destrutivas necessárias
• Complexa: Exigindo múltiplas chamadas de ferramenta e exploração aprofundada
• Realista: Baseada em casos de uso reais que humanos considerariam importantes
• Verificável: Resposta única e clara que pode ser verificada por comparação de strings
• Estável: Resposta não muda com o tempo

4.4 Formato de Saída

Crie um arquivo XML com esta estrutura:

<evaluation>
  <qa_pair>
    <question>Encontre discussões sobre lançamentos de modelos de IA com codinomes de animais. Um modelo precisava de uma designação de segurança específica que usa o formato ASL-X. Qual número X estava sendo determinado para o modelo nomeado em homenagem a um gato selvagem manchado?</question>
    <answer>3</answer>
  </qa_pair>
<!-- Mais qa_pairs... -->
</evaluation>

---

Arquivos de Referência

📚 Biblioteca de Documentação

Carregue esses recursos conforme necessário durante o desenvolvimento:

Documentação Principal do MCP (Carregar Primeiro)

• Protocolo MCP: Comece com o mapa do site em https://modelcontextprotocol.io/sitemap.xml, depois busque páginas específicas com o sufixo .md
• 📋 Práticas Recomendadas de MCP - Diretrizes universais de MCP incluindo:
  • Convenções de nomenclatura de servidores e ferramentas
  • Diretrizes de formato de resposta (JSON vs Markdown)
  • Melhores práticas de paginação
  • Seleção de transporte (HTTP streamable vs stdio)
  • Padrões de segurança e tratamento de erros

Documentação do SDK (Carregar Durante a Fase 1/2)

• SDK Python: Buscar de https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• SDK TypeScript: Buscar de https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Guias de Implementação Específicos de Linguagem (Carregar Durante a Fase 2)

• 🐍 Guia de Implementação Python
• ⚡ Guia de Implementação TypeScript

Guia de Avaliação (Carregar Durante a Fase 4)

• ✅ Guia de Avaliação

---

Parte 2: Exemplar de Skill com Injeção de Contexto Dinâmica do Claude Code (!comando``)

• Fonte: Documentação de Skills do Claude Code

---
name: pr-summary
description: Resume alterações em um pull request. Use quando o usuário pedir para revisar, resumir ou auditar o PR atual ou diff do branch.
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Contexto do Pull Request
- Diff do PR: !`gh pr diff`
- Comentários do PR: !`gh pr view --comments`
- Arquivos alterados: !`gh pr diff --name-only`

## Sua tarefa
Resuma este pull request com riscos concretos em nível de arquivo, mudanças impactantes e etapas de verificação...

---

Parte 3: Esquema Sidecar agents/openai.yaml do OpenAI Codex / ChatGPT

• Fonte: Documentação de Build de Skills do OpenAI

interface:
  display_name: "Meta-Prompt Auto-Evolutivo e Arquiteto de Papéis"
  short_description: "Compile, avalie e adapte Prompts, Skills e Papéis de Agentes entre ferramentas"
  icon_small: "./assets/icon-small.svg"
  icon_large: "./assets/icon-large.png"
  brand_color: "#2563EB"
  default_prompt: "Projete ou otimize uma definição de prompt, skill ou papel de agente com um scorecard de avaliação."

policy:
  allow_implicit_invocation: true

dependencies:
  tools:
    - type: "mcp"
      value: "git"
      description: "Servidor MCP Git para inspeção de repositório"

---

Parte 4: Exemplar de Script Autossuficiente para Agentes PEP 723

• Fonte: Agent Skills — Usando Scripts (agentskills.io)

# /// script
# dependencies = [
#   "pydantic>=2.0",
# ]
# requires-python = ">=3.10"
# ///
"""Script CLI autossuficiente não interativo projetado para invocação de Skill de Agente via `uv run`."""

import argparse
import json
import sys


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Valide frontmatter de skill ou papel e orçamento de token sem prompts interativos."
    )
    parser.add_argument("--input", required=True, help="Caminho para o arquivo Markdown alvo")
    parser.add_argument("--max-chars", type=int, default=12000, help="Teto do orçamento de caracteres")
    parser.add_argument("--dry-run", action="store_true", help="Visualize verificações sem escrever")
    args = parser.parse_args()

    try:
        with open(args.input, "r", encoding="utf-8") as f:
            text = f.read()
    except FileNotFoundError:
        sys.stderr.write(
            f"Erro: Arquivo '{args.input}' não encontrado. Passe um caminho válido via --input <caminho>.\n"
        )
        return 1

    char_count = len(text)
    passed = char_count <= args.max_chars
    result = {
        "file": args.input,
        "char_count": char_count,
        "max_chars": args.max_chars,
        "passed": passed,
        "remediation": None if passed else f"Pode {char_count - args.max_chars} caracteres ou mova detalhes para referências/.",
    }
    sys.stdout.write(json.dumps(result, ensure_ascii=False, indent=2) + "\n")
    return 0 if passed else 2


if __name__ == "__main__":
    sys.exit(main())