Agent Skills

Agent Skills é um padrão aberto para ampliar os recursos dos agentes de IA com capacidades especializadas. As skills reúnem conhecimentos e fluxos de trabalho específicos de um domínio que os agentes podem usar para executar tarefas específicas.

O que são skills?

Uma skill é um pacote portátil e versionado que ensina agentes a realizar tarefas específicas de um domínio. As skills podem incluir scripts, templates e referências que os agentes podem usar com suas ferramentas.

Como as skills funcionam

Ao iniciar, o Cursor detecta automaticamente as skills nos diretórios de skills e as disponibiliza ao agente. O agente recebe as skills disponíveis e decide quando elas são relevantes com base no contexto.

As skills também podem ser invocadas manualmente digitando / no chat do agente e pesquisando o nome da skill. Uma skill invocada dessa forma é anexada a uma mensagem. Para usá-la como um Modo personalizado durante toda a sessão, use Option+EnterAlt+Enter (Mac) ou Alt+Enter (Windows). Consulte Modos personalizados.

Skills integradas do Cursor

O Cursor inclui um pequeno conjunto de skills integradas para aprimorar seus fluxos de trabalho. Essas skills são gerenciadas pelo Cursor e aparecem ao lado das skills que você adiciona.

Você pode executar qualquer skill integrada digitando / no chat do Agente e selecionando seu nome. O agente também pode usar algumas skills integradas automaticamente quando sua solicitação corresponder claramente à finalidade delas.

Diretórios de skills

As skills são carregadas automaticamente destes diretórios:

Por compatibilidade, o Cursor também carrega skills dos diretórios do Claude e do Codex: .claude/skills/, .codex/skills/, ~/.claude/skills/ e ~/.codex/skills/.

Cada skill deve ser uma pasta que contenha um arquivo SKILL.md:

.agents/└── skills/    └── my-skill/        └── SKILL.md

As skills também podem incluir diretórios opcionais para scripts, referências e recursos estáticos:

.agents/└── skills/    └── deploy-app/        ├── SKILL.md        ├── scripts/        │   ├── deploy.sh        │   └── validate.py        ├── references/        │   └── REFERENCE.md        └── assets/            └── config-template.json

Diretórios de skills aninhados

Os diretórios de skills podem ser organizados em subdiretórios. Isso é útil para agrupar skills relacionadas por categoria, equipe ou domínio. O Cursor percorre recursivamente o diretório raiz de skills e identifica todos os arquivos SKILL.md:

.cursor/└── skills/    ├── shipping/    │   ├── land-it/    │   │   └── SKILL.md    │   └── careful-merge-conflicts/    │       └── SKILL.md    ├── debugging/    │   └── using-datadog-mcp/    │       └── SKILL.md    └── workflow/        └── tdd/            └── SKILL.md

A pasta de categoria serve apenas para organização. A identidade da skill vem da pasta que contém SKILL.md (neste caso, land-it, tdd etc.), e não da categoria pai.

O Cursor também detecta skills em subdiretórios aninhados do projeto. Uma pasta .cursor/skills/ (ou .agents/skills/) em qualquer lugar do repositório é detectada, permitindo que monorepos mantenham as skills junto ao pacote a que se aplicam:

my-monorepo/├── .cursor/skills/         # skills de todo o repositório│   └── land-it/SKILL.md└── apps/    └── web/        └── .cursor/skills/  # skills específicas do app            └── deploy-web/SKILL.md

As skills em diretórios de projeto aninhados são automaticamente aplicadas aos arquivos desse diretório. No exemplo acima, deploy-web só é disponibilizada quando o agente trabalha com arquivos em apps/web/, enquanto as skills em .cursor/skills/ na raiz do repositório estão disponíveis em qualquer lugar. Isso é semelhante ao campo paths do frontmatter — não é necessário definir paths em uma skill aninhada para aplicá-la ao respectivo diretório.

Formato do arquivo SKILL.md

Cada skill é definida em um arquivo SKILL.md com frontmatter YAML:

---name: my-skilldescription: Short description of what this skill does and when to use it.---# My SkillDetailed instructions for the agent.## When to Use- Use this skill when...- This skill is helpful for...## Instructions- Step-by-step guidance for the agent- Domain-specific conventions- Best practices and patterns- Use the ask questions tool if you need to clarify requirements with the user

Campos do frontmatter

Restringindo uma skill a arquivos específicos

Use o campo paths para restringir uma skill a arquivos que correspondam a um ou mais padrões glob. A skill só será apresentada ao agente quando ele estiver lendo ou editando arquivos correspondentes. Isso mantém orientações específicas para arquivos fora do contexto de trabalhos não relacionados.

---name: react-component-patternsdescription: Conventions for writing React components in this codebase.paths:  - "**/*.tsx"  - "packages/ui/**/*.ts"---# React component patterns...

Também é possível passar uma única string separada por vírgulas:

---name: python-styledescription: Style rules for Python files.paths: "**/*.py, scripts/**/*.py"---

Os padrões seguem a sintaxe glob padrão. Deixe paths sem definir para que uma skill fique disponível independentemente dos arquivos abertos.

Desativando a invocação automática

Por padrão, as skills são aplicadas automaticamente quando o agente determina que são relevantes. Defina disable-model-invocation: true para que uma skill funcione como um comando slash tradicional, sendo incluída no contexto apenas quando você digitar explicitamente /skill-name no chat.

Usar uma skill como Modo Personalizado

Qualquer skill com um bloco de frontmatter válido pode servir como um Modo Personalizado, mantendo a skill no contexto durante toda a sessão. Um modo ativo exibe um indicador no campo de mensagem do chat. Personalize-o com os campos opcionais icon e color do frontmatter:

---name: tdddescription: Test-driven development playbook for this repo.icon: beakercolor: green---

Os ícones vêm do conjunto de ícones do Cursor, com nomes como code, terminal, bug, git-branch, book-open, beaker, shield e rocket. Ícones ou cores não reconhecidos usam o selo padrão, representado por um ícone de raio.

Inclusão de scripts em skills

As skills podem incluir um diretório scripts/ com código executável pelos agentes. Faça referência aos scripts no seu SKILL.md usando caminhos relativos à raiz da skill.

---name: deploy-appdescription: Deploy the application to staging or production environments. Use when deploying code or when the user mentions deployment, releases, or environments.---# Deploy AppDeploy the application using the provided scripts.## UsageRun the deployment script: `scripts/deploy.sh <environment>`Where `<environment>` is either `staging` or `production`.## Pre-deployment ValidationBefore deploying, run the validation script: `python scripts/validate.py`

O agente lê estas instruções e executa os scripts referenciados quando a habilidade é acionada. Os scripts podem ser escritos em qualquer linguagem — Bash, Python, JavaScript ou qualquer outro formato executável compatível com a implementação do agente.

Diretórios opcionais

As skills oferecem suporte aos seguintes diretórios opcionais:

Mantenha o SKILL.md principal focado e mova o material de referência detalhado para arquivos separados. Assim, o uso de contexto permanece eficiente, pois os agentes carregam recursos progressivamente — apenas quando necessário.

Como ver skills

Para ver as skills encontradas, abra Personalizar na barra lateral e vá para Skills. As skills instaladas por plugins ou no seu projeto aparecem junto às regras na seção Agente Decide.

Como instalar skills do GitHub

Você pode importar skills de repositórios do GitHub:

1. Abra Customize na barra lateral
2. Acesse Rules e clique em Add Rule
3. Selecione Remote Rule (GitHub)
4. Insira a URL do repositório do GitHub

Migração de regras e comandos para skills

O Cursor inclui uma skill integrada, /migrate-to-skills, na versão 2.4, que ajuda a converter regras dinâmicas e comandos slash existentes em skills.

A skill de migração converte:

• Regras dinâmicas: regras que usam a configuração "Aplicar de forma inteligente" — ou seja, regras com alwaysApply: false (ou undefined) e sem padrões globs definidos. Elas são convertidas em skills padrão.
• Comandos slash: comandos no nível do usuário e do espaço de trabalho são convertidos em skills com disable-model-invocation: true, preservando seu comportamento de invocação explícita.

Para migrar:

1. Digite /migrate-to-skills no chat do agente
2. O agente identificará as regras e os comandos qualificados e os converterá em skills
3. Revise as skills geradas em .cursor/skills/

Saiba mais

O Agent Skills é um padrão aberto. Saiba mais em agentskills.io.

Relacionado

• Ajuda sobre Skills

• Use sua própria máquina