Agent Skills no Cursor: do Primeiro SKILL.md a Workflows com MCP

Uma Skill no Cursor não é uma habilidade mágica do modelo nem apenas um prompt salvo. É um pacote versionável de conhecimento, instruções e recursos que ensina o Agent a executar um fluxo específico de forma repetível.

Neste guia vamos construir uma Skill real para publicar artigos neste portfólio. No caminho, você vai entender descoberta automática, SKILL.md, escopo, progressive disclosure, Rules, MCP, scripts e os erros que fazem uma Skill parecer boa no papel, mas falhar no uso diário.

1. O problema que uma Skill resolve

Imagine pedir várias vezes: leia o guia do projeto, pesquise fontes confiáveis, escreva em três idiomas, registre no índice e valide o build. Repetir tudo em cada conversa é lento e sujeito a esquecimento. Uma Skill transforma esse conhecimento operacional em parte do repositório.

• ▸Padroniza tarefas recorrentes sem depender da memória da conversa.
• ▸Viaja com o repositório e pode passar por code review.
• ▸Pode incluir referências, templates, assets e scripts executáveis.
• ▸É carregada apenas quando relevante, economizando contexto.

2. Como o Cursor descobre e carrega Skills

Ao iniciar, o Cursor procura diretórios de Skills e apresenta ao Agent principalmente o nome e a descrição. Quando a tarefa combina com essa descrição, o Agent lê o SKILL.md completo. Arquivos auxiliares são carregados somente se necessários. Esse processo é chamado de progressive disclosure.

No Cursor, os locais mais comuns são .cursor/skills/ para o projeto e ~/.cursor/skills/ para uso pessoal. O padrão aberto também usa .agents/skills/ e ~/.agents/skills/. Cada Skill vive em uma pasta própria, e o nome dessa pasta deve corresponder ao campo name.

.cursor/
└── skills/
    └── publicar-artigo/
        ├── SKILL.md
        ├── references/
        │   └── formato-artigos.md
        └── scripts/
            └── validar-artigo.mjs

3. Anatomia do SKILL.md

O arquivo possui duas partes: frontmatter YAML entre delimitadores --- e instruções em Markdown. name e description são obrigatórios. No Cursor, paths, disable-model-invocation e metadata são campos opcionais.

---
name: publicar-artigo
description: Cria e registra artigos multilíngues neste portfólio. Use quando o usuário pedir para escrever, publicar ou revisar um artigo em lib/articles.
---

# Publicar artigo

1. Leia lib/articles/COMO-ADICIONAR-ARTIGOS.md.
2. Consulte fontes primárias sobre o tema.
3. Crie o conteúdo equivalente em pt, en e zh.
4. Registre o artigo em lib/articles/index.ts.
5. Execute lint e build.
6. Informe as fontes utilizadas e os resultados da validação.

name: identidade previsível

Use letras minúsculas, números e hífens, com no máximo 64 caracteres. O nome não deve começar nem terminar com hífen e precisa ser igual ao diretório: publicar-artigo/SKILL.md usa name: publicar-artigo.

description: o mecanismo de descoberta

A description precisa responder duas perguntas: o que a Skill faz e quando deve ser usada. Uma descrição como Ajuda com artigos é vaga. Cria e registra artigos multilíngues; use quando o usuário pedir para escrever, publicar ou revisar um artigo oferece verbos, objetos e gatilhos claros.

4. Automática, manual e limitada por arquivos

Por padrão, o Agent pode aplicar uma Skill automaticamente quando julga que ela é relevante. Você também pode executá-la digitando / e escolhendo seu nome, ou usar @nome-da-skill para anexá-la explicitamente como contexto.

Use paths para mostrar a Skill apenas quando o trabalho envolver arquivos compatíveis. Isso reduz ativações indevidas e mantém instruções específicas fora de tarefas não relacionadas.

---
name: revisar-componentes-react
description: Revisa componentes React deste projeto seguindo os padrões locais. Use ao criar, alterar ou revisar componentes TSX.
paths:
  - "components/**/*.tsx"
  - "app/**/*.tsx"
---

# Revisar componentes React

- Verifique acessibilidade e navegação por teclado.
- Preserve os tokens visuais existentes.
- Evite estado duplicado e efeitos desnecessários.
- Rode lint nos arquivos alterados.

Para operações sensíveis ou que sempre exigem intenção explícita, configure disable-model-invocation: true. Nesse modo, a Skill só entra em contexto quando alguém chama /deploy-producao.

---
name: deploy-producao
description: Valida e executa o deploy de produção com checklist de segurança.
disable-model-invocation: true
---

# Deploy de produção

Só prossiga após confirmar ambiente, branch e plano de rollback.

5. Skill, Rule, MCP ou subagent?

Essas extensões se complementam, mas resolvem problemas diferentes. Escolher a ferramenta errada cria contexto desnecessário ou concede capacidades que o workflow não precisa.

Uma Rule diz como o Agent deve se comportar continuamente. Uma Skill ensina como concluir uma classe de tarefas. MCP não ensina o processo: ele fornece ferramentas, recursos e acesso a sistemas externos. Uma Skill pode orientar quando e como usar um MCP.

6. Construindo a Skill deste portfólio

A primeira versão deve ser pequena e executável. Ela começa lendo a fonte de verdade do projeto, exige pesquisa em fontes primárias, preserva os três idiomas, registra o artigo e valida o resultado.

Passo 1: crie o diretório

mkdir -p .cursor/skills/publicar-artigo
touch .cursor/skills/publicar-artigo/SKILL.md

Passo 2: escreva instruções verificáveis

Prefira passos que possam ser observados. Pesquise bem é subjetivo; consulte documentação oficial, liste as URLs nas referências e diferencie fatos de opinião produz resultados verificáveis.

• ▸Defina a fonte de verdade antes de editar.
• ▸Explique quais arquivos devem ser criados ou atualizados.
• ▸Declare os idiomas e a equivalência esperada entre blocos.
• ▸Inclua comandos de validação e critérios de sucesso.
• ▸Diga como agir diante de informação ausente ou contraditória.

Passo 3: mova detalhes para references/

O SKILL.md deve conter o caminho feliz. Formatos extensos, glossários e políticas podem ir para references/. O Agent carrega esse material somente quando a execução pede, em vez de ocupar contexto em toda ativação.

Passo 4: automatize validações determinísticas

Não peça ao modelo para conferir visualmente tudo que um script pode validar com precisão. Uma Skill pode incluir scripts em qualquer linguagem suportada pelo ambiente e referenciá-los por caminho relativo.

import { readFileSync } from "node:fs";

const file = process.argv[2];
const source = readFileSync(file, "utf8");

const required = [
  'published: true',
  'publishedAt:',
  'titles:',
  'description:',
  'body: { pt:',
];

const missing = required.filter((item) => !source.includes(item));

if (missing.length > 0) {
  console.error("Campos ausentes:", missing.join(", "));
  process.exit(1);
}

console.log("Artigo validado:", file);

No SKILL.md, a instrução pode ser: execute node scripts/validar-artigo.mjs lib/articles/<slug>.ts e só prossiga se o exit code for zero. Para validação completa, mantenha também lint, testes e build do projeto.

7. Testando se a Skill realmente funciona

Uma Skill não está pronta porque o Markdown parece claro. Teste ativação, não ativação e qualidade da execução. Abra Customize > Skills para confirmar que ela foi descoberta e experimente prompts reais.

• ▸A Skill abriu os arquivos corretos antes de editar?
• ▸As fontes citadas sustentam as afirmações?
• ▸O Agent respeitou o formato e os três idiomas?
• ▸Os validadores detectaram uma versão propositalmente inválida?
• ▸A Skill ficou inativa em tarefas não relacionadas?

8. Skills e MCP trabalhando juntos

MCP conecta o Cursor a ferramentas e dados externos. Uma Skill pode definir o processo: consultar uma issue no Linear, buscar métricas no Grafana, alterar o código, executar testes e devolver um relatório. O MCP oferece a capacidade; a Skill organiza a sequência e as decisões.

Em integrações MCP, use credenciais por variáveis de ambiente, permissões mínimas e servidores confiáveis. Revise argumentos antes de autorizar ferramentas com escrita. Nunca coloque tokens em SKILL.md, scripts versionados ou exemplos de configuração.

9. Erros comuns

• ▸Criar uma Skill genérica que tenta resolver dezenas de workflows.
• ▸Escrever uma description sem dizer quando ativar.
• ▸Colocar toda a documentação no SKILL.md e desperdiçar contexto.
• ▸Duplicar em uma Skill regras que deveriam ser persistentes.
• ▸Depender de comandos destrutivos sem confirmação ou rollback.
• ▸Codificar datas, versões ou APIs sem fontes e estratégia de atualização.
• ▸Não testar prompts negativos, causando ativações acidentais.
• ▸Confundir acesso fornecido por MCP com instruções fornecidas por Skill.

10. Checklist de uma Skill profissional

• ▸A pasta e o campo name são iguais e usam kebab-case.
• ▸A description explica o que faz e quando usar.
• ▸O escopo é pequeno o suficiente para ser previsível.
• ▸O fluxo tem entradas, etapas, validação e saída claras.
• ▸Detalhes longos estão em references/; automações em scripts/.
• ▸Operações sensíveis exigem intenção e confirmação explícitas.
• ▸Existem testes positivos, negativos e de paráfrase.
• ▸A Skill não contém segredos nem permissões excessivas.
• ▸O repositório versiona e revisa a Skill como qualquer código.

Conclusão

A melhor Skill não é a mais longa: é a que transforma conhecimento tácito em um processo curto, acionável e verificável. Comece por uma tarefa repetitiva, escreva uma description precisa, extraia validações para scripts e evolua com falhas observadas em uso real.

Quando Skills, Rules e MCP são usados nos papéis corretos, o Cursor deixa de ser apenas um chat que conhece código e passa a operar como um membro do time que conhece seus processos, sem esconder que ainda precisa de revisão, limites e evidências.

Referências

• ▸Cursor Docs, Agent Skills: https://cursor.com/docs/skills
• ▸Cursor Docs, Customize Cursor: https://cursor.com/docs/customize-cursor
• ▸Cursor Docs, Rules: https://cursor.com/docs/rules
• ▸Cursor Docs, Model Context Protocol (MCP): https://cursor.com/docs/mcp
• ▸Cursor Docs, segurança do Agent: https://cursor.com/docs/agent/security
• ▸Cursor Docs, Run Modes e sandbox: https://cursor.com/docs/agent/security/run-modes
• ▸Agent Skills, visão geral do padrão aberto: https://agentskills.io/home
• ▸Agent Skills, especificação do SKILL.md: https://agentskills.io/specification
• ▸Agent Skills, guia rápido de criação: https://agentskills.io/skill-creation/quickstart