{"meta":{"title":"Custom skills","intro":"Skills are reusable prompt modules that extend Copilot's capabilities. Load skills from directories to give Copilot specialized abilities for specific domains or workflows.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/how-tos","title":"How-tos"},{"href":"/en/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/en/copilot/how-tos/copilot-sdk/features","title":"Features"},{"href":"/en/copilot/how-tos/copilot-sdk/features/skills","title":"Skills"}],"documentType":"article"},"body":"# Custom skills\n\nSkills are reusable prompt modules that extend Copilot's capabilities. Load skills from directories to give Copilot specialized abilities for specific domains or workflows.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Overview\n\nA skill is a named directory containing a `SKILL.md` file—a markdown document that provides instructions to Copilot. When loaded, the skill's content is injected into the session context.\n\nSkills allow you to:\n\n* Package domain expertise into reusable modules\n* Share specialized behaviors across projects\n* Organize complex agent configurations\n* Enable/disable capabilities per session\n\n## Loading skills\n\nSpecify directories containing skills when creating a session:\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## Disabling skills\n\nDisable specific skills while keeping others active:\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## Skill directory structure\n\nEach skill is a named subdirectory containing a `SKILL.md` file:\n\n```text\nskills/\n├── code-review/\n│   └── SKILL.md\n└── documentation/\n    └── SKILL.md\n```\n\nThe `skillDirectories` option points to the parent directory (e.g., `./skills`). The CLI discovers all `SKILL.md` files in immediate subdirectories.\n\n### SKILL.md format\n\nA `SKILL.md` file is a markdown document with optional YAML frontmatter:\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\nThe frontmatter fields:\n\n* **`name`**: The skill's identifier (used with `disabledSkills` to selectively disable it). If omitted, the directory name is used.\n* **`description`**: A short description of what the skill does.\n\nThe markdown body contains the instructions that are injected into the session context when the skill is loaded.\n\n## Configuration options\n\n### SessionConfig skill fields\n\n| Language | Field               | Type           | Description                     |\n| -------- | ------------------- | -------------- | ------------------------------- |\n| Node.js  | `skillDirectories`  | `string[]`     | Directories to load skills from |\n| Node.js  | `disabledSkills`    | `string[]`     | Skills to disable               |\n| Python   | `skill_directories` | `list[str]`    | Directories to load skills from |\n| Python   | `disabled_skills`   | `list[str]`    | Skills to disable               |\n| Go       | `SkillDirectories`  | `[]string`     | Directories to load skills from |\n| Go       | `DisabledSkills`    | `[]string`     | Skills to disable               |\n| .NET     | `SkillDirectories`  | `List<string>` | Directories to load skills from |\n| .NET     | `DisabledSkills`    | `List<string>` | Skills to disable               |\n\n## Best practices\n\n1. **Organize by domain** - Group related skills together (e.g., `skills/security/`, `skills/testing/`)\n\n2. **Use frontmatter** - Include `name` and `description` in YAML frontmatter for clarity\n\n3. **Document dependencies** - Note any tools or MCP servers a skill requires\n\n4. **Test skills in isolation** - Verify skills work before combining them\n\n5. **Use relative paths** - Keep skills portable across environments\n\n## Combining with other features\n\n### Skills + custom agents\n\nSkills listed in an agent's `skills` field are **eagerly preloaded**—their full content is injected into the agent's context at startup, so the agent has access to the skill instructions immediately without needing to invoke a skill tool. Skill names are resolved from the session-level `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> Skills are opt-in—when `skills` is omitted, no skill content is injected. Sub-agents do not inherit skills from the parent; you must list them explicitly per agent.\n\n### Skills + MCP servers\n\nSkills can complement MCP server capabilities:\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### Skills not loading\n\n1. **Check path exists** - Verify the skill directory path is correct and contains subdirectories with `SKILL.md` files\n2. **Check permissions** - Ensure the SDK can read the directory\n3. **Check SKILL.md format** - Verify the markdown is well-formed and any YAML frontmatter uses valid syntax\n4. **Enable debug logging** - Set `logLevel: \"debug\"` to see skill loading logs\n\n### Skill conflicts\n\nIf multiple skills provide conflicting instructions:\n\n* Use `disabledSkills` to exclude conflicting skills\n* Reorganize skill directories to avoid overlaps\n\n## See also\n\n* [Build your first Copilot-powered app](/en/copilot/how-tos/copilot-sdk/getting-started#create-custom-agents) - Define specialized AI personas\n* [Build your first Copilot-powered app](/en/copilot/how-tos/copilot-sdk/getting-started#step-4-add-a-custom-tool) - Build your own tools\n* [Using MCP servers with the GitHub Copilot SDK](/en/copilot/how-tos/copilot-sdk/features/mcp) - Connect external tool providers"}