Pesquisa de sites

Como Escrever e Implementar Competências de Agente

Introdução

Competências de Agente são pastas de instruções, scripts e recursos que um Modelo de Linguagem de Grande Escala (LLM) pode carregar quando relevante para executar tarefas especializadas de forma consistente e repetível. Foram introduzidas como um framework aberto por Claude em 2025, e o framework tem sido cada vez mais adotado por outras organizações e desenvolvedores de agentes desde então.

No passado, ao atribuir uma tarefa a um LLM, era necessário fornecer manualmente o contexto para o fluxo de trabalho do LLM. Com as Competências de Agente, é possível separar recursos e instruções adicionais em pastas que só podem ser acedidas quando o LLM identificar que são necessárias.

Por exemplo, se quiser que o seu LLM crie apresentações em PowerPoint, em vez de adicionar manualmente os guias de estilo, gráficos e modelos da sua organização no prompt todas as vezes, pode adicioná-los a uma pasta como uma Skill e o LLM poderá encontrar e usar os recursos de forma independente sempre que precisar de criar uma apresentação. Pode adicionar um grande número de Skills, e os LLMs podem consultá-las como ferramentas.

Neste tutorial, irá criar uma Competência de Agente para um analisador de PDF, com pastas opcionais para outros documentos de referência e recursos.

Principais Conclusões

  • As Competências do Agente são pastas que contêm um ficheiro SKILL.md com metadados e instruções que permitem aos LLMs carregar funcionalidades especializadas apenas quando relevantes, em vez de exigir todo o contexto em cada prompt. O Claude introduziu esta estrutura em 2025, e ela permite fluxos de trabalho de agentes mais eficientes ao separar os recursos em módulos acessíveis de forma independente.

  • Para os agentes utilizarem competências, precisam ser capazes de as descobrir, carregar e executar. Isto envolve analisar as competências disponíveis e encontrar a mais adequada ao pedido de um utilizador.

  • As competências dos agentes provavelmente se tornarão um padrão importante para adicionar capacidades aos agentes. Elas oferecem muita personalização e potencial dinâmico para os agentes.

Passo 1 — Criar a Competência

A implementação mais simples de uma competência é uma pasta que contém um ficheiro SKILL.md. Este ficheiro markdown inclui metadados e instruções para o agente que explicam como realizar tarefas específicas. Também pode incluir recursos adicionais, modelos, scripts e materiais de referência na pasta.

Folder Structure
your-skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

O nome da pasta da Skill será o nome da Skill. Depois, dentro da pasta, encontra-se o ficheiro SKILL.md e quaisquer materiais adicionais que queira incluir.

Primeiro, crie uma pasta chamada skills. Esta pasta irá conter todas as Skills que você criar. Dentro da pasta skills, crie outra pasta chamada pdf-parsing. Esta pasta irá conter todos os ficheiros e documentação da sua Skill de pdf-parsing. Dentro da pasta pdf-parsing, crie um ficheiro SKILL.md com o seguinte conteúdo.

---
name: pdf-processing
description: Extracts text from PDF files using PyPDF2.
---

# PDF Processing Skill

## When to use this skill
Use this skill when a user needs to extract text from a PDF file.

## How to Use this Skill
This skill provides the `extract_text()` function from the `parse_pdf.py` script. Import it into your agent script:

python
from skills.pdf_parsing.parse_pdf import extract_text

result = extract_text(
    file_path="/path/to/document.pdf",
    pages="all"  # or "1-3" or "1,2,3"
)

### Parameters
- `file_path` (str): Path to the PDF file
- `pages` (str): Pages to extract - "all", "1-3" (range), or "1,2,3" (specific pages)

### Returns
JSON object with:
- `success` (bool): Whether extraction succeeded
- `file_path` (str): Path to the processed file
- `total_pages` (int): Total pages in PDF
- `extracted_pages` (int): Number of pages extracted
- `pages` (list): Array of {page: number, text: string} objects

Alternatively, you can call the script directly from the command line:
command
python skills/pdf-parsing/parse_pdf.py extract_text --file_path /path/to/file.pdf --pages all

O name e a description são obrigatórios no topo do ficheiro markdown no frontmatter para que o agente consiga extrair as descrições. O frontmatter é a seção no topo do ficheiro markdown que contém os metadados. O agente vai usar estes campos de cada Skill para identificar qual Skill é melhor para um pedido. Pode incluir campos opcionais no frontmatter, incluindo license, compatibility, metadata e allowed-tools. Para fluxos de trabalho de agentes personalizados, pode adicionar quaisquer campos que desejar. O agente irá incluir o frontmatter de cada skill com o pedido do utilizador para identificar qual Skill é apropriada.

Para o resto do corpo do markdown, não existem requisitos específicos para as instruções. Tente seguir as melhores práticas de prompting e mantenha as instruções claras para que o LLM as possa seguir. O restante do corpo será consultado após o agente ter determinado qual Competência utilizar.

Depois, use este script gratuito de análise de PDF ou crie um ficheiro parse_pdf.py com uma função extract_text() com a funcionalidade de análise de PDFs. Certifique-se de instalar todas as dependências cada vez que adicionar uma Skill. Para o script ligado, precisará do PyPDF2.

pip3 install PyPDF2

Isto irá instalar o pacote Python PyPDF2.

Passo 2 — Integrar a Competência

Para que as Skills possam ser usadas por um agente, o agente precisa seguir certos passos. É necessário descobrir as Skills em todos os diretórios com o ficheiro SKILL.md, carregar os metadados (nome e descrição) de cada ficheiro markdown na inicialização, corresponder o pedido do utilizador às Skills relevantes, ativar as Skills carregando as instruções completas do ficheiro markdown, e executar a Skill carregando os ficheiros referenciados, seguindo as instruções e executando o código conforme necessário.

Alguns agentes, como o Claude Code e o Codex, integram automaticamente as Competências nos seus fluxos de trabalho, e um número crescente de fornecedores de agentes está a integrar estes passos nos fluxos de trabalho dos seus agentes.

Se quiser integrar a sua competência num agente personalizado, existem duas formas principais de o fazer. Pode usar um padrão baseado em sistema de ficheiros ou um padrão baseado em ferramentas. Com um padrão baseado em sistema de ficheiros, o fluxo de trabalho do LLM opera dentro de um ambiente de computador e gera comandos de shell como cat /path/to/my-skill/skill.md que são depois executados. Alternativamente, a abordagem baseada em ferramentas transforma efetivamente as Competências em ferramentas que o LLM pode chamar.

Construir um agente com capacidades de Skill a partir do zero está fora do alcance deste tutorial, mas você pode usar este script de agente. O script utiliza o Llama 3.3 70B através da ferramenta Serverless Inference da plataforma Linux-Console.net Gradient AI. Será necessário obter uma chave de acesso ao modelo para usar o Serverless Inference na plataforma Linux-Console.net Gradient AI. Adicione a sua chave de acesso ao modelo na função main() do script.

Depois de ter o script na mesma pasta que a sua pasta skills, execute o script.

python3 agent_example.py

Na caixa de texto que se abre para si, introduza: Please parse the text out of the PDF at /path/to/your/document.pdf. Deverá ver uma saída com o texto extraído do PDF.

============================================================
SIMPLE TOOL-BASED SKILLS EXAMPLE
============================================================

✅ Found 1 skills:
   - pdf-processing: Extracts text from PDF files using PyPDF2.

============================================================
CHAT (type 'quit' to exit)
============================================================

You: Please extract the text from: /Desktop/document.pdf

[Turn 1]
💭 LLM: {"function_call": {"name": "activate_skill", "arguments": {"skill_name": "pdf-processing"}}}
..........
The cost of an RV is 30,000

O agente encontrou com sucesso a Competência, extraiu os metadados, executou a Competência e devolveu o texto do PDF.

Passo 3 — Adicionar Funcionalidade e Competências

Adicione quaisquer outros scripts ou pastas aos quais gostaria que o LLM tivesse acesso. Depois, adicione instruções e descrições da funcionalidade de cada pasta e script no ficheiro SKILL.md. Por exemplo, pode adicionar scripts que possam gerar ou editar PDFs. Certifique-se de adicionar estes ficheiros adicionais na pasta da competência específica com a qual pretende associá-los.

É possível adicionar quantas Competências desejar, mas cada pasta de Competência deve ter um ficheiro SKILL.md na pasta para ser reconhecida pelo agente. Além disso, pode ser difícil para um agente associar a intenção do utilizador aos metadados de muitas Competências, pelo que, à medida que o número de Competências aumenta, pode ser necessário adicionar funcionalidades de pesquisa adicionais ou usar embeddings vetoriais para corresponder o pedido do utilizador à competência correta.

Perguntas Frequentes

As Skills podem comunicar entre si ou chamar outras Skills, e como implementaria a encadeamento de Skills?

Sim, as Skills podem chamar outras Skills. O agente deve ser capaz de reconhecer quando várias Skills podem ser necessárias e encadeá-las. Também é possível referenciar outras Skills nas instruções da skill.

Como faço para gerir a autenticação e as chaves de API dentro das Skills quando precisam de aceder a serviços externos?

Nunca codifique credenciais diretamente nos ficheiros da skill. Utilize variáveis de ambiente ou um gestor de segredos seguro.

Quais são as implicações de desempenho ao carregar muitas Skills no arranque, e existem estratégias de carregamento preguiçoso disponíveis?

Carregar os metadados de centenas de Skills pode ser lento. Considere guardar em cache os Skills carregados e usar indexação para uma pesquisa mais rápida entre muitos Skills. Pode separar as etapas de descoberta e ativação para carregar os metadados apenas até que o Skill completo seja necessário.

Como posso testar e depurar Skills?

Certifique-se de testar as Skills individualmente antes de as integrar e adicione registo detalhado às suas Skills para ver quais estão a ser selecionadas e porquê.

Conclusão

As Competências do Agente são uma excelente forma de padronizar a funcionalidade de um agente LLM. Permitem aos utilizadores adicionar e melhorar as capacidades do agente de forma estruturada. A forma como as implementa depende do seu fluxo de trabalho específico do agente, mas o número de serviços de agente que podem utilizar Competências imediatamente está a aumentar, com Claude Code, Codex e VSCode a serem apenas alguns dos fornecedores de agentes que adotaram este standard.

De seguida, adicione mais Competências e personalize-as com funcionalidades adicionais que sejam apropriadas para o seu projeto. Depois, melhore as capacidades de correspondência de competências do seu fluxo de trabalho do agente através de embeddings vetoriais ou outra funcionalidade de pesquisa.

Obrigado por aprender com a comunidade Linux-Console.net.