{"meta":{"title":"Habilidades personalizadas","intro":"As habilidades são módulos reutilizáveis de prompt que expandem os recursos do Copilot. Carregue habilidades a partir de diretórios para fornecer ao Copilot capacidades especializadas em domínios específicos ou fluxos de trabalho.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/copilot","title":"GitHub Copilot"},{"href":"/pt/copilot/how-tos","title":"Instruções"},{"href":"/pt/copilot/how-tos/copilot-sdk","title":"SDK do Copilot"},{"href":"/pt/copilot/how-tos/copilot-sdk/features","title":"Features"},{"href":"/pt/copilot/how-tos/copilot-sdk/features/skills","title":"Habilidades"}],"documentType":"article"},"body":"# Habilidades personalizadas\n\nAs habilidades são módulos reutilizáveis de prompt que expandem os recursos do Copilot. Carregue habilidades a partir de diretórios para fornecer ao Copilot capacidades especializadas em domínios específicos ou fluxos de trabalho.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Overview\n\nUma habilidade é um diretório nomeado que contém um arquivo `SKILL.md` — um documento markdown que fornece instruções para Copilot. Quando carregado, o conteúdo da habilidade é injetado no contexto da sessão.\n\nAs habilidades permitem que você:\n\n* Empacotar expertise de domínio em módulos reutilizáveis\n* Compartilhar comportamentos especializados entre projetos\n* Organizar configurações complexas do agente\n* Habilitar/desabilitar recursos por sessão\n\n## Carregando habilidades\n\nEspecifique os diretórios que contêm habilidades ao criar uma sessão:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nconst session = await client.createSession({\n    model: \"gpt-5.4\",\n    skillDirectories: [\n        \"./skills/code-review\",\n        \"./skills/documentation\",\n    ],\n    onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n\n// Copilot now has access to skills in those directories\nawait session.sendAndWait({ prompt: \"Review this code for security issues\" });\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient, PermissionDecisionApproveOnce\n\nasync def main():\n    client = CopilotClient()\n    await client.start()\n\n    session = await client.create_session(\n        on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n        model=\"gpt-5.4\",\n        skill_directories=[\n            \"./skills/code-review\",\n            \"./skills/documentation\",\n        ],\n    )\n\n    # Copilot now has access to skills in those directories\n    await session.send_and_wait(\"Review this code for security issues\")\n\n    await client.stop()\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    copilot \"github.com/github/copilot-sdk/go\"\n    \"github.com/github/copilot-sdk/go/rpc\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    client := copilot.NewClient(nil)\n    if err := client.Start(ctx); err != nil {\n        log.Fatal(err)\n    }\n    defer client.Stop()\n\n    session, err := client.CreateSession(ctx, &copilot.SessionConfig{\n        Model: \"gpt-5.4\",\n        SkillDirectories: []string{\n            \"./skills/code-review\",\n            \"./skills/documentation\",\n        },\n        OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {\n            return &rpc.PermissionDecisionApproveOnce{}, nil\n        },\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    // Copilot now has access to skills in those directories\n    _, err = session.SendAndWait(ctx, copilot.MessageOptions{\n        Prompt: \"Review this code for security issues\",\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nusing GitHub.Copilot;\nusing GitHub.Copilot.Rpc;\n\nawait using var client = new CopilotClient();\nawait using var session = await client.CreateSessionAsync(new SessionConfig\n{\n    Model = \"gpt-5.4\",\n    SkillDirectories = new List<string>\n    {\n        \"./skills/code-review\",\n        \"./skills/documentation\",\n    },\n    OnPermissionRequest = (req, inv) =>\n        Task.FromResult(PermissionDecision.ApproveOnce()),\n});\n\n// Copilot now has access to skills in those directories\nawait session.SendAndWaitAsync(new MessageOptions\n{\n    Prompt = \"Review this code for security issues\"\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\nimport java.util.List;\n\ntry (var client = new CopilotClient()) {\n    client.start().get();\n\n    var session = client.createSession(\n        new SessionConfig()\n            .setModel(\"gpt-5.4\")\n            .setSkillDirectories(List.of(\n                \"./skills/code-review\",\n                \"./skills/documentation\"\n            ))\n            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n    ).get();\n\n    // Copilot now has access to skills in those directories\n    session.sendAndWait(new MessageOptions()\n        .setPrompt(\"Review this code for security issues\")\n    ).get();\n}\n```\n\n</div>\n\n</div>\n\n## Desativando funcionalidades\n\nDesabilite habilidades específicas mantendo outras pessoas ativas:\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nconst session = await client.createSession({\n    skillDirectories: [\"./skills\"],\n    disabledSkills: [\"experimental-feature\", \"deprecated-tool\"],\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot.session import PermissionHandler\n\nsession = await client.create_session(\n    on_permission_request=PermissionHandler.approve_all,\n    skill_directories=[\"./skills\"],\n    disabled_skills=[\"experimental-feature\", \"deprecated-tool\"],\n)\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nsession, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{\n    SkillDirectories: []string{\"./skills\"},\n    DisabledSkills:   []string{\"experimental-feature\", \"deprecated-tool\"},\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nvar session = await client.CreateSessionAsync(new SessionConfig\n{\n    SkillDirectories = new List<string> { \"./skills\" },\n    DisabledSkills = new List<string> { \"experimental-feature\", \"deprecated-tool\" },\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n<!-- docs-validate: skip -->\n\n```java\nimport com.github.copilot.rpc.*;\nimport java.util.List;\n\nvar session = client.createSession(\n    new SessionConfig()\n        .setSkillDirectories(List.of(\"./skills\"))\n        .setDisabledSkills(List.of(\"experimental-feature\", \"deprecated-tool\"))\n        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n).get();\n```\n\n</div>\n\n</div>\n\n## Estrutura do diretório de habilidades\n\nCada habilidade é um subdiretório nomeado que contém um `SKILL.md` arquivo:\n\n```text\nskills/\n├── code-review/\n│   └── SKILL.md\n└── documentation/\n    └── SKILL.md\n```\n\nA `skillDirectories` opção aponta para o diretório pai (por exemplo, `./skills`). A CLI descobre todos os `SKILL.md` arquivos em subdiretórios imediatos.\n\n### formato SKILL.md\n\nUm `SKILL.md` arquivo é um documento de markdown com metadados YAML opcionais:\n\n```markdown\n---\nname: code-review\ndescription: Specialized code review capabilities\n---\n\n# Code Review Guidelines\n\nWhen reviewing code, always check for:\n\n1. **Security vulnerabilities** - SQL injection, XSS, etc.\n2. **Performance issues** - N+1 queries, memory leaks\n3. **Code style** - Consistent formatting, naming conventions\n4. **Test coverage** - Are critical paths tested?\n\nProvide specific line-number references and suggested fixes.\n```\n\nOs campos de elementos iniciais:\n\n* **`name`**: o identificador da habilidade (usado com `disabledSkills` para desativá-la seletivamente). Se omitido, o nome do diretório será usado.\n* **`description`**: uma breve descrição do que a habilidade faz.\n\nO corpo do markdown contém as instruções que são injetadas no contexto da sessão quando a habilidade é carregada.\n\n## Opções de configuração\n\n### Campos de habilidade SessionConfig\n\n| Linguagem | Campo               | Tipo           | Description                             |\n| --------- | ------------------- | -------------- | --------------------------------------- |\n| Node.js   | `skillDirectories`  | `string[]`     | Diretórios para carregar habilidades de |\n| Node.js   | `disabledSkills`    | `string[]`     | Funções a desativar                     |\n| Python    | `skill_directories` | `list[str]`    | Diretórios para carregar habilidades de |\n| Python    | `disabled_skills`   | `list[str]`    | Funções a desativar                     |\n| Go        | `SkillDirectories`  | `[]string`     | Diretórios para carregar habilidades de |\n| Go        | `DisabledSkills`    | `[]string`     | Funções a desativar                     |\n| .NET      | `SkillDirectories`  | `List<string>` | Diretórios para carregar habilidades de |\n| .NET      | `DisabledSkills`    | `List<string>` | Funções a desativar                     |\n\n## Práticas recomendadas\n\n1. **Organizar por domínio** – Agrupar habilidades relacionadas (por exemplo, `skills/security/`, ) `skills/testing/`\n\n2. **Usar frontmatter** – Incluir `name` e `description` no frontmatter do YAML para maior clareza\n\n3. **Dependências de documento** – Observe as ferramentas ou servidores MCP que uma habilidade requer\n\n4. **Testar habilidades isoladamente** – Verificar se as habilidades funcionam antes de combiná-las\n\n5. **Usar caminhos relativos – Manter as habilidades portáveis entre ambientes**\n\n## Combinando com outros recursos\n\n### Habilidades + agentes personalizados\n\nAs habilidades listadas no campo de `skills` um agente são **ansiosamente pré-carregadas**– seu conteúdo completo é injetado no contexto do agente na inicialização, portanto, o agente tem acesso às instruções de habilidade imediatamente sem precisar invocar uma ferramenta de habilidade. Os nomes de habilidade são resolvidos no nível da sessão `skillDirectories`.\n\n```typescript\nconst session = await client.createSession({\n    skillDirectories: [\"./skills/security\"],\n    customAgents: [{\n        name: \"security-auditor\",\n        description: \"Security-focused code reviewer\",\n        prompt: \"Focus on OWASP Top 10 vulnerabilities\",\n        skills: [\"security-scan\", \"dependency-check\"],\n    }],\n    onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n> \\[!NOTE]\n> As habilidades são opcionais — quando `skills` é omitido, nenhum conteúdo de habilidades é injetado. Os sub-agentes não herdam habilidades do pai; você deve listá-los explicitamente por agente.\n\n### Habilidades + servidores MCP\n\nAs habilidades podem complementar os recursos do servidor MCP:\n\n```typescript\nconst session = await client.createSession({\n    skillDirectories: [\"./skills/database\"],\n    mcpServers: {\n        postgres: {\n            type: \"local\",\n            command: \"npx\",\n            args: [\"-y\", \"@modelcontextprotocol/server-postgres\"],\n            tools: [\"*\"],\n        },\n    },\n    onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n```\n\n## Troubleshooting\n\n### Habilidades que não estão carregando\n\n1. **Caminho de verificação existe** - Verifique se o caminho do diretório de habilidades está correto e contém subdiretórios com `SKILL.md` arquivos\n2. **Verificar permissões** – verifique se o SDK pode ler o diretório\n3. **Verificar o formato de SKILL.md** — certifique-se de que o markdown está bem formado e que qualquer frontmatter YAML use sintaxe válida\n4. **Habilitar o registro em log de depuração** — defina `logLevel: \"debug\"` para ver os logs de carregamento de habilidades\n\n### Conflitos de habilidades\n\nSe várias habilidades fornecerem instruções conflitantes:\n\n* Usar `disabledSkills` para excluir habilidades conflitantes\n* Reorganizar diretórios de habilidades para evitar sobreposições\n\n## Consulte também\n\n* [Crie seu primeiro aplicativo com tecnologia do Copilot](/pt/copilot/how-tos/copilot-sdk/getting-started#create-custom-agents) – Definir personas de IA especializadas\n* [Crie seu primeiro aplicativo com tecnologia do Copilot](/pt/copilot/how-tos/copilot-sdk/getting-started#step-4-add-a-custom-tool) – Criar suas próprias ferramentas\n* [Usando servidores MCP com o SDK do GitHub Copilot](/pt/copilot/how-tos/copilot-sdk/features/mcp) – Conectar provedores de ferramentas externas"}