Merge branch 'main' into copilot/review-code-changes

Resolve merge conflicts in 4 files:
- dotnet/src/Client.cs: Keep MergeExcludedTools with main's non-nullable config access
- go/client.go: Keep mergeExcludedTools with main's direct config access (no nil guard)
- go/client_test.go: Keep both MergeExcludedTools tests and permission handler tests
- python/test_client.py: Merge imports (both define_tool and PermissionHandler)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: patniko

docs/auth/byok.md

@@ -10,6 +10,7 @@ BYOK allows you to use the Copilot SDK with your own API keys from model provide
 | Azure OpenAI / Azure AI Foundry | `"azure"` | Azure-hosted models |
 | Anthropic | `"anthropic"` | Claude models |
 | Ollama | `"openai"` | Local models via OpenAI-compatible API |
+| Microsoft Foundry Local | `"openai"` | Run AI models locally on your device via OpenAI-compatible API |
 | Other OpenAI-compatible | `"openai"` | vLLM, LiteLLM, etc. |
 
 ## Quick Start: Azure AI Foundry
@@ -250,6 +251,37 @@ provider: {
 }
 ```
 
+### Microsoft Foundry Local
+
+[Microsoft Foundry Local](https://foundrylocal.ai) lets you run AI models locally on your own device with an OpenAI-compatible API. Install it via the Foundry Local CLI, then point the SDK at your local endpoint:
+
+```typescript
+provider: {
+    type: "openai",
+    baseUrl: "http://localhost:<PORT>/v1",
+    // No apiKey needed for local Foundry Local
+}
+```
+
+> **Note:** Foundry Local starts on a **dynamic port** — the port is not fixed. Use `foundry service status` to confirm the port the service is currently listening on, then use that port in your `baseUrl`.
+
+To get started with Foundry Local:
+
+```bash
+# Windows: Install Foundry Local CLI (requires winget)
+winget install Microsoft.FoundryLocal
+
+# macOS / Linux: see https://foundrylocal.ai for installation instructions
+# List available models
+foundry model list
+
+# Run a model (starts the local server automatically)
+foundry model run phi-4-mini
+
+# Check the port the service is running on
+foundry service status
+```
+
 ### Anthropic
 
 ```typescript
@@ -305,6 +337,7 @@ Some Copilot features may behave differently with BYOK:
 |----------|-------------|
 | Azure AI Foundry | No Entra ID auth; must use API keys |
 | Ollama | No API key; local only; model support varies |
+| [Microsoft Foundry Local](https://foundrylocal.ai) | Local only; model availability depends on device hardware; no API key required |
 | OpenAI | Subject to OpenAI rate limits and quotas |
 
 ## Troubleshooting
@@ -368,6 +401,21 @@ curl http://localhost:11434/v1/models
 ollama serve
 ```
 
+### Connection Refused (Foundry Local)
+
+Foundry Local uses a dynamic port that may change between restarts. Confirm the active port:
+
+```bash
+# Check the service status and port
+foundry service status
+```
+
+Update your `baseUrl` to match the port shown in the output. If the service is not running, start a model to launch it:
+
+```bash
+foundry model run phi-4-mini
+```
+
 ### Authentication Failed
 
 1. Verify your API key is correct and not expired

docs/getting-started.md

@@ -1193,14 +1193,14 @@ Once the CLI is running in server mode, configure your SDK client to connect to
 <summary><strong>Node.js / TypeScript</strong></summary>
 
 ```typescript
-import { CopilotClient } from "@github/copilot-sdk";
+import { CopilotClient, approveAll } from "@github/copilot-sdk";
 
 const client = new CopilotClient({
     cliUrl: "localhost:4321"
 });
 
 // Use the client normally
-const session = await client.createSession();
+const session = await client.createSession({ onPermissionRequest: approveAll });
 // ...
 ```
 
@@ -1210,15 +1210,15 @@ const session = await client.createSession();
 <summary><strong>Python</strong></summary>
 
 ```python
-from copilot import CopilotClient
+from copilot import CopilotClient, PermissionHandler
 
 client = CopilotClient({
     "cli_url": "localhost:4321"
 })
 await client.start()
 
 # Use the client normally
-session = await client.create_session()
+session = await client.create_session({"on_permission_request": PermissionHandler.approve_all})
 # ...
 ```
 
@@ -1241,7 +1241,9 @@ if err := client.Start(ctx); err != nil {
 defer client.Stop()
 
 // Use the client normally
-session, err := client.CreateSession(ctx, nil)
+session, err := client.CreateSession(ctx, &copilot.SessionConfig{
+    OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+})
 // ...
 ```
 
@@ -1260,7 +1262,10 @@ using var client = new CopilotClient(new CopilotClientOptions
 });
 
 // Use the client normally
-await using var session = await client.CreateSessionAsync();
+await using var session = await client.CreateSessionAsync(new()
+{
+    OnPermissionRequest = PermissionHandler.ApproveAll
+});
 // ...
 ```
 

docs/guides/skills.md

@@ -1,13 +1,10 @@
 # Custom Skills
 
-Skills are reusable collections of prompts, tools, and configuration that extend Copilot's capabilities. Load skills from directories to give Copilot specialized abilities for specific domains or workflows.
+Skills are reusable prompt modules that extend Copilot's capabilities. Load skills from directories to give Copilot specialized abilities for specific domains or workflows.
 
 ## Overview
 
-A skill is a directory containing:
-- **Prompt files** - Instructions that guide Copilot's behavior
-- **Tool definitions** - Custom tools the skill provides
-- **Configuration** - Metadata about the skill
+A 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.
 
 Skills allow you to:
 - Package domain expertise into reusable modules
@@ -31,8 +28,8 @@ const session = await client.createSession({
     skillDirectories: [
         "./skills/code-review",
         "./skills/documentation",
-        "~/.copilot/skills",  // User-level skills
     ],
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 
 // Copilot now has access to skills in those directories
@@ -56,8 +53,8 @@ async def main():
         "skill_directories": [
             "./skills/code-review",
             "./skills/documentation",
-            "~/.copilot/skills",  # User-level skills
         ],
+        "on_permission_request": lambda req: {"kind": "approved"},
     })
 
     # Copilot now has access to skills in those directories
@@ -93,7 +90,9 @@ func main() {
         SkillDirectories: []string{
             "./skills/code-review",
             "./skills/documentation",
-            "~/.copilot/skills",  // User-level skills
+        },
+        OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
+            return copilot.PermissionRequestResult{Kind: "approved"}, nil
         },
     })
     if err != nil {
@@ -126,8 +125,9 @@ await using var session = await client.CreateSessionAsync(new SessionConfig
     {
         "./skills/code-review",
         "./skills/documentation",
-        "~/.copilot/skills",  // User-level skills
     },
+    OnPermissionRequest = (req, inv) =>
+        Task.FromResult(new PermissionRequestResult { Kind = "approved" }),
 });
 
 // Copilot now has access to skills in those directories
@@ -196,41 +196,28 @@ var session = await client.CreateSessionAsync(new SessionConfig
 
 ## Skill Directory Structure
 
-A typical skill directory contains:
+Each skill is a named subdirectory containing a `SKILL.md` file:
 
 ```
 skills/
-└── code-review/
-    ├── skill.json          # Skill metadata and configuration
-    ├── prompts/
-    │   ├── system.md       # System prompt additions
-    │   └── examples.md     # Few-shot examples
-    └── tools/
-        └── lint.json       # Tool definitions
+├── code-review/
+│   └── SKILL.md
+└── documentation/
+    └── SKILL.md
 ```
 
-### skill.json
-
-The skill manifest file:
+The `skillDirectories` option points to the parent directory (e.g., `./skills`). The CLI discovers all `SKILL.md` files in immediate subdirectories.
 
-```json
-{
-  "name": "code-review",
-  "displayName": "Code Review Assistant",
-  "description": "Specialized code review capabilities",
-  "version": "1.0.0",
-  "author": "Your Team",
-  "prompts": ["prompts/system.md"],
-  "tools": ["tools/lint.json"]
-}
-```
+### SKILL.md Format
 
-### Prompt Files
-
-Markdown files that provide context to Copilot:
+A `SKILL.md` file is a markdown document with optional YAML frontmatter:
 
 ```markdown
-<!-- prompts/system.md -->
+---
+name: code-review
+description: Specialized code review capabilities
+---
+
 # Code Review Guidelines
 
 When reviewing code, always check for:
@@ -243,6 +230,12 @@ When reviewing code, always check for:
 Provide specific line-number references and suggested fixes.
 ```
 
+The frontmatter fields:
+- **`name`** — The skill's identifier (used with `disabledSkills` to selectively disable it). If omitted, the directory name is used.
+- **`description`** — A short description of what the skill does.
+
+The markdown body contains the instructions that are injected into the session context when the skill is loaded.
+
 ## Configuration Options
 
 ### SessionConfig Skill Fields
@@ -262,7 +255,7 @@ Provide specific line-number references and suggested fixes.
 
 1. **Organize by domain** - Group related skills together (e.g., `skills/security/`, `skills/testing/`)
 
-2. **Version your skills** - Include version numbers in `skill.json` for compatibility tracking
+2. **Use frontmatter** - Include `name` and `description` in YAML frontmatter for clarity
 
 3. **Document dependencies** - Note any tools or MCP servers a skill requires
 
@@ -284,6 +277,7 @@ const session = await client.createSession({
         description: "Security-focused code reviewer",
         prompt: "Focus on OWASP Top 10 vulnerabilities",
     }],
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 
@@ -302,23 +296,24 @@ const session = await client.createSession({
             tools: ["*"],
         },
     },
+    onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
 
 ## Troubleshooting
 
 ### Skills Not Loading
 
-1. **Check path exists** - Verify the directory path is correct
+1. **Check path exists** - Verify the skill directory path is correct and contains subdirectories with `SKILL.md` files
 2. **Check permissions** - Ensure the SDK can read the directory
-3. **Validate skill.json** - Check for JSON syntax errors
+3. **Check SKILL.md format** - Verify the markdown is well-formed and any YAML frontmatter uses valid syntax
 4. **Enable debug logging** - Set `logLevel: "debug"` to see skill loading logs
 
 ### Skill Conflicts
 
-If multiple skills define the same tool:
-- Later directories in the array take precedence
+If multiple skills provide conflicting instructions:
 - Use `disabledSkills` to exclude conflicting skills
+- Reorganize skill directories to avoid overlaps
 
 ## See Also
 

dotnet/README.md

@@ -77,8 +77,8 @@ new CopilotClient(CopilotClientOptions? options = null)
 - `Cwd` - Working directory for the CLI process
 - `Environment` - Environment variables to pass to the CLI process
 - `Logger` - `ILogger` instance for SDK logging
-- `GithubToken` - GitHub token for authentication. When provided, takes priority over other auth methods.
-- `UseLoggedInUser` - Whether to use logged-in user for authentication (default: true, but false when `GithubToken` is provided). Cannot be used with `CliUrl`.
+- `GitHubToken` - GitHub token for authentication. When provided, takes priority over other auth methods.
+- `UseLoggedInUser` - Whether to use logged-in user for authentication (default: true, but false when `GitHubToken` is provided). Cannot be used with `CliUrl`.
 
 #### Methods