Como escrever skills

Uma skill é um procedimento com nome que o assistente pode invocar, em vez de deduzir os passos de novo a cada vez. As memórias dizem ao assistente o que é verdade. As regras dizem o que ele não deve fazer. As skills dizem como executar uma tarefa específica, passo a passo.

Esta página explica quando escrever uma skill, o que vai dentro dela e como as skills são armazenadas e vinculadas.

Quando escrever uma skill

Recorra a uma skill quando perceber o mesmo padrão se repetindo. O sinal é: "o assistente sempre percorre o mesmo conjunto de passos e às vezes esquece um deles".

• Procedimentos operacionais. "Reenviar um webhook do Stripe localmente." "Regerar as fixtures de seed." "Executar o checklist de pré-release."
• Fluxos de trabalho personalizados. "Abrir um PR em rascunho com as labels e os revisores certos." "Subir a versão, criar a tag e fazer o push."
• Orientações específicas do domínio. "Criar um novo evento de analytics de ponta a ponta: coluna, tipo, dashboard."

Se o padrão cabe em uma ou duas linhas, uma memória é suficiente. Recorra a uma skill quando o procedimento tiver mais de três passos ou trouxer qualquer exigência do tipo "faça nesta ordem".

Fontes

Todo registro de skill tem um valor de fonte que indica ao Pathrule onde fica o corpo dela.

• manual. O corpo é escrito diretamente no Pathrule e armazenado como está. É o padrão. Use quando quiser que o procedimento pertença inteiramente ao espaço de trabalho.
• template. Uma skill inicial fornecida pelo Pathrule, copiada para o espaço de trabalho e editável a partir dali.
• github_ref. A skill aponta para uma URL externa do GitHub. Use para skills publicadas por ecossistemas de skills em que você confia.

Nas skills github_ref, o espaço de trabalho guarda um snapshot do corpo obtido dessa fonte, e a skill fica somente leitura no espaço de trabalho: o VS Code orienta você a editar a fonte.

Estrutura do SKILL.md

Uma skill é um pequeno arquivo Markdown com frontmatter seguido do corpo do procedimento.

---
name: replay-stripe-webhook
description: Replay a Stripe webhook against the local server with the right signing secret and the right idempotency key handling.
---

# Replay a Stripe webhook

Use this when a payment event from production needs to be reproduced locally.

## When to invoke

- A customer reports a missing receipt and you have the event id.
- You are debugging a webhook handler change.

## Procedure

1. Find the event in Stripe Dashboard. Copy its id.
2. Run `stripe events resend evt_xxx --webhook-endpoint we_local`.
3. Watch the local handler. It must accept and process the event without double charging.
4. If the handler returns 5xx, the customer support page is the next stop, not a retry.

## What NOT to do

- Do not replay against production webhooks.
- Do not skip the idempotency key check.

O frontmatter precisa incluir name e description. Tudo o que vem abaixo é o corpo que o assistente segue. O corpo pode ser tão curto ou tão longo quanto for necessário.

Vinculação

Uma skill fica em um único caminho do espaço de trabalho, do mesmo jeito que uma regra. Coloque-a no caminho onde o procedimento é mais relevante. A skill de reenvio de webhook vai em services/billing/webhooks. A skill de release vai na raiz do espaço de trabalho. Uma nova skill cujo nome coincida com o de uma skill já existente no espaço de trabalho é recusada; então atualize a existente em vez de criar uma segunda cópia.

O assistente descobre as skills pelo contexto que o Pathrule entrega para um caminho (da mesma forma que descobre memórias e regras), por meio de pathrule_get_context, e lê uma skill completa com pathrule_read_skill. Na sincronização, o Pathrule também grava as skills nas pastas de skills dos clientes que as leem, como .claude/skills no Claude Code e .agents/skills no Codex.

Invoque uma skill sob demanda com ::skill-name

Normalmente o assistente escolhe sozinho a skill certa. Quando você quiser forçar uma específica, digite :: seguido do nome da skill em qualquer lugar do prompt, por exemplo ::release-check ou ::replay-stripe-webhook. Naquele turno, o assistente trata a skill indicada como um fluxo de trabalho obrigatório, sem que você precise escrever instruções longas. No Claude Code e no Codex, o hook de prompt captura o marcador antes de o agente agir; nos outros clientes, o assistente recebe a mesma instrução quando solicita contexto via MCP.

O recurso foi projetado para falhar de forma segura:

• Se o nome corresponder a mais de uma skill, nenhuma skill é invocada, em vez de o assistente tentar adivinhar.
• Se o nome não corresponder a nenhuma skill, o assistente é instruído a parar e resolver a questão com você antes de editar qualquer coisa. Ele pode sugerir candidatas publicadas e espera sua aprovação antes de adicionar alguma ao espaço de trabalho.
• Usos de :: com cara de código, como button::before ou std::vector, são ignorados, então prompts comuns não são mal interpretados.

Isso faz de ::skill-name uma forma rápida e independente de caminho de trazer um procedimento conhecido da equipe para o turno atual.

Fluxo de criação

Dois fluxos levam ao mesmo resultado.

• Criação manual. No VS Code, use New Skill… no caminho certo e escreva o corpo do SKILL.md. No terminal, execute pathrule skill add --path /services/billing/webhooks --name replay-stripe-webhook --description "Replay a Stripe webhook locally"; sem --body, o CLI abre o seu editor.
• Criação pelo assistente. No Claude Code (ou em qualquer cliente MCP), o usuário pede ao assistente para "transformar isso em uma skill". O assistente segue um pequeno padrão de criação de skills: entende a intenção, faz perguntas ao usuário, escreve um rascunho do SKILL.md e então chama pathrule_write_skill com o corpo completo.

Em cenários de baixo comprometimento, o assistente redige a skill na própria conversa e espera a aprovação antes de chamar pathrule_write_skill. Assim, o registro salvo é o rascunho revisado, e não uma gravação silenciosa em segundo plano.

Versionamento e edições simultâneas

As skills têm um token de versão, assim como memórias e regras. Quando duas pessoas da equipe editam a mesma skill, o conflito é tratado de forma limpa, sem que uma edição sobrescreva a outra, com as mesmas opções de resolução de conflito no VS Code que existem para uma memória.

Antipadrões

• Skills que na verdade são memórias. Se o corpo diz "isto é verdade sobre a forma como trabalhamos", transforme em uma memória.
• Skills que na verdade são regras. Se o corpo diz "nunca faça X", transforme em uma regra.
• Uma skill que faz coisas demais. Divida em duas skills com nomes próprios se o procedimento tiver dois pontos de entrada distintos.
• Trazer skills externas em que você não confia. Uma skill github_ref é código que roda nas instruções do seu assistente. Trate-a como uma dependência.

Criação no modo local e no Cloud

Os exemplos de add no terminal desta página se aplicam a um espaço de trabalho no Cloud. No modo local, crie e edite entradas no Local Console, no VS Code ou via MCP local; os comandos de conhecimento do CLI listam, leem e pesquisam essas entradas.

O que ler em seguida

• Como escrever memórias, para fatos e decisões.
• Como escrever regras, para restrições.
• Referência das ferramentas MCP, para as ferramentas que o assistente usa para gravar skills.