From 9c7c1771a805d81e1b86bc888551ce07036140d4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 7 Apr 2026 19:45:41 +0000 Subject: [PATCH] =?UTF-8?q?docs(learning-hub):=20document=20new=20hooks,?= =?UTF-8?q?=20Critic=20agent,=20and=20built-in=20skills=20(v1.0.16?= =?UTF-8?q?=E2=80=93v1.0.18)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - automating-with-hooks.md: add notification (async) and PermissionRequest hook events to the events table; update key characteristics to note the notification hook fires asynchronously; document permissionDecision output field for preToolUse; add PermissionRequest practical example - building-custom-agents.md: add FAQ entry for the new Critic agent (experimental Claude-model feature that auto-reviews plans) - creating-effective-skills.md: mention CLI-bundled built-in skills available out of the box (added in v1.0.17) Sources: - https://github.com/github/copilot-cli/releases/tag/v1.0.16 (PermissionRequest hook) - https://github.com/github/copilot-cli/releases/tag/v1.0.17 (built-in skills) - https://github.com/github/copilot-cli/releases/tag/v1.0.18 (Critic agent, notification hook, permissionDecision) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../learning-hub/automating-with-hooks.md | 74 ++++++++++++++++++- .../learning-hub/building-custom-agents.md | 6 +- .../learning-hub/creating-effective-skills.md | 4 +- 3 files changed, 79 insertions(+), 5 deletions(-) diff --git a/website/src/content/docs/learning-hub/automating-with-hooks.md b/website/src/content/docs/learning-hub/automating-with-hooks.md index 6e1b7c7a..e83c2a4c 100644 --- a/website/src/content/docs/learning-hub/automating-with-hooks.md +++ b/website/src/content/docs/learning-hub/automating-with-hooks.md @@ -3,7 +3,7 @@ title: 'Automating with Hooks' description: 'Learn how to use hooks to automate lifecycle events like formatting, linting, and governance checks during Copilot agent sessions.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-04-01 +lastUpdated: 2026-04-07 estimatedReadingTime: '8 minutes' tags: - hooks @@ -26,7 +26,8 @@ Hooks are shell commands or scripts that run automatically in response to lifecy **Key characteristics**: - Hooks run as shell commands on the user's machine -- They execute synchronously—the agent waits for them to complete +- Most hooks execute synchronously—the agent waits for them to complete before continuing +- The `notification` hook is an exception: it fires **asynchronously** without blocking the agent - They can block actions (e.g., prevent commits that fail linting) - They're defined in JSON files stored at `.github/hooks/*.json` in your repository - They receive detailed context via JSON input, enabling context-aware automation @@ -98,8 +99,12 @@ Hooks can trigger on several lifecycle events: | `subagentStart` | A subagent is spawned by the main agent | Inject additional context into the subagent's prompt, log subagent launches | | `subagentStop` | A subagent completes before returning results | Audit subagent outputs, log subagent activity | | `errorOccurred` | An error occurs during agent execution | Log errors for debugging, send notifications, track error patterns | +| `PermissionRequest` | Copilot requests user permission to run a tool | Programmatically approve or deny tool permission prompts without user interaction | +| `notification` *(async)* | Shell command completes, a permission prompt appears, an elicitation dialog fires, or the agent completes | Send non-blocking notifications (Slack, Teams, desktop), log events without delaying the agent | -> **Key insight**: The `preToolUse` hook is the most powerful — it can **approve or deny** individual tool executions. This enables fine-grained security policies like blocking specific shell commands or requiring approval for sensitive file operations. +> **Key insight**: The `preToolUse` hook is the most powerful — it can **approve or deny** individual tool executions. This enables fine-grained security policies like blocking specific shell commands or requiring approval for sensitive file operations. When your hook script outputs `{"permissionDecision": "allow"}` to stdout, the tool's built-in approval prompt is suppressed and the tool runs immediately — useful for whitelisting safe, repetitive operations without repeated prompts. + +> **Automatic approvals with `PermissionRequest`**: The `PermissionRequest` hook fires specifically when Copilot's permission UI would appear. Use it to auto-approve or deny requests programmatically (e.g., always allow read-only operations, always deny destructive writes in production paths) without interrupting the user. ### sessionStart additionalContext @@ -295,6 +300,41 @@ Block dangerous commands before they execute: The `preToolUse` hook receives JSON input with details about the tool being called. Your script can inspect this input and exit with a non-zero code to **deny** the tool execution, or exit with zero to **approve** it. +To **automatically approve** a specific tool without showing the built-in permission prompt, output `{"permissionDecision": "allow"}` to stdout from your hook script: + +```bash +#!/usr/bin/env bash +# Auto-approve read-only tools, prompt for everything else +INPUT=$(cat) +TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty') +if [[ "$TOOL" == "codebase" || "$TOOL" == "search" ]]; then + echo '{"permissionDecision": "allow"}' +fi +# Exit 0 without output to use the default prompt behavior +``` + +### Auto-Approving with PermissionRequest + +The `PermissionRequest` hook fires specifically when Copilot's built-in permission UI would display a prompt. Use it to auto-approve or deny requests programmatically: + +```json +{ + "version": 1, + "hooks": { + "PermissionRequest": [ + { + "type": "command", + "bash": "./scripts/auto-approve-permissions.sh", + "cwd": ".", + "timeoutSec": 5 + } + ] + } +} +``` + +Your script receives the permission request details via JSON stdin and can output `{"permissionDecision": "allow"}` or `{"permissionDecision": "deny"}` to handle it programmatically, or exit without output to fall back to the default UI prompt. + ### Governance Audit Scan user prompts for potential security threats and log session activity: @@ -337,6 +377,34 @@ Scan user prompts for potential security threats and log session activity: This pattern is useful for enterprise environments that need to audit AI interactions for compliance. +### Non-Blocking Notifications with the notification Hook + +The `notification` hook fires **asynchronously** — the agent doesn't wait for it to complete. This makes it ideal for notification-style integrations where you want to be informed of events without adding latency to the agent's workflow: + +```json +{ + "version": 1, + "hooks": { + "notification": [ + { + "type": "command", + "bash": "./scripts/notify.sh", + "cwd": ".", + "timeoutSec": 10 + } + ] + } +} +``` + +The `notification` hook fires on: +- **Shell command completion** — a terminal command the agent ran has finished +- **Permission prompts** — Copilot is requesting permission to use a tool +- **Elicitation dialogs** — Copilot needs additional user input +- **Agent completion** — the agent has finished responding + +Because it's asynchronous, this hook is great for sending Slack or Teams messages, updating dashboards, or logging to external systems — without adding any delay to the agent's work. + ### Notification on Session End Send a Slack or Teams notification when an agent session completes: diff --git a/website/src/content/docs/learning-hub/building-custom-agents.md b/website/src/content/docs/learning-hub/building-custom-agents.md index 95e8beb9..453511e9 100644 --- a/website/src/content/docs/learning-hub/building-custom-agents.md +++ b/website/src/content/docs/learning-hub/building-custom-agents.md @@ -3,7 +3,7 @@ title: 'Building Custom Agents' description: 'Learn how to create specialized GitHub Copilot agents with custom personas, tool integrations, and domain expertise.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-02-26 +lastUpdated: 2026-04-07 estimatedReadingTime: '10 minutes' tags: - agents @@ -263,6 +263,10 @@ Keep agents focused—one persona per file. If you find an agent trying to do to A: In VS Code, open Copilot Chat and use the agent picker dropdown at the top of the chat panel. Your custom agents appear alongside built-in options. You can also `@mention` an agent by name. +**Q: What is the Critic agent?** + +A: The **Critic agent** is a built-in experimental feature (available for Claude models) that automatically reviews plans and complex implementations using a complementary model. When enabled, it runs in parallel with the primary agent to catch errors, inconsistencies, and missed requirements early — before you see the result. To try it, enable experimental mode when working with a Claude-powered agent. + **Q: Can agents use skills?** A: Yes. Agents can discover and invoke skills during a conversation based on the user's intent. Skills extend what an agent can do without bloating the agent's own instructions. diff --git a/website/src/content/docs/learning-hub/creating-effective-skills.md b/website/src/content/docs/learning-hub/creating-effective-skills.md index 1cf91101..2fad702b 100644 --- a/website/src/content/docs/learning-hub/creating-effective-skills.md +++ b/website/src/content/docs/learning-hub/creating-effective-skills.md @@ -3,7 +3,7 @@ title: 'Creating Effective Skills' description: 'Master the art of writing reusable, shareable skill folders that deliver consistent results across your team.' authors: - GitHub Copilot Learning Hub Team -lastUpdated: 2026-02-26 +lastUpdated: 2026-04-07 estimatedReadingTime: '9 minutes' tags: - skills @@ -18,6 +18,8 @@ prerequisites: Skills are self-contained folders that package reusable capabilities—instructions, reference files, templates, and scripts—into a single unit that agents can discover automatically and users can invoke via slash commands. They enable teams to standardize common workflows like generating tests, reviewing code, or creating documentation, ensuring consistent, high-quality results across all team members. +GitHub Copilot CLI also ships with a set of **built-in skills** that are available out of the box. These cover common tasks like customizing the Copilot cloud agent's environment. You can browse and invoke them just like custom skills, and they serve as useful examples when building your own. + This article shows you how to design, structure, and optimize skills that solve real development challenges. ## What Are Skills?