Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 77 additions & 1 deletion website/src/content/docs/learning-hub/automating-with-hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-04
estimatedReadingTime: '8 minutes'
tags:
- hooks
Expand Down Expand Up @@ -98,6 +98,8 @@ 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` | When the agent is about to show a permission approval dialog | Programmatically approve or deny permission requests without user interaction |
| `notification` | **Asynchronously** after shell completion, permission prompts, elicitation dialogs, or agent completion | Send async system alerts and log events without blocking 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.

Expand Down Expand Up @@ -125,6 +127,80 @@ When multiple IDE extensions (or a mix of extensions and a `hooks.json` file) ea

Hook event names can be written in **camelCase** (e.g., `preToolUse`) or **PascalCase** (e.g., `PreToolUse`). Both are accepted, making hook configuration files compatible across GitHub Copilot CLI, VS Code, and Claude Code without modification. Hooks also support Claude Code's nested `matcher`/`hooks` structure alongside the standard flat format.

### PermissionRequest Hook

The `PermissionRequest` hook fires when the agent is about to display a **permission approval dialog** — a prompt asking the user to allow or deny a specific tool use or action. This lets you write scripts that approve trusted actions automatically without requiring manual user interaction.

```json
{
"version": 1,
"hooks": {
"PermissionRequest": [
{
"type": "command",
"bash": "./scripts/auto-approve.sh",
"cwd": ".",
"timeoutSec": 5
}
]
}
}
```

Unlike `preToolUse` (which runs before *every* tool call), `PermissionRequest` fires specifically for the interactive permission dialogs — making it suitable for CI/CD environments or unattended sessions where you want fully automated approvals for known-safe operations.

### Enhanced preToolUse: permissionDecision Output

In addition to controlling tool execution via exit codes, `preToolUse` hooks can now output a JSON object with a `permissionDecision` field. When the hook script writes `{"permissionDecision": "allow"}` to stdout, the tool approval prompt is **suppressed** and the tool proceeds without user confirmation:

```bash
#!/usr/bin/env bash
# Auto-approve read-only tools, block destructive ones
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')

case "$TOOL" in
view|glob|grep|read)
echo '{"permissionDecision": "allow"}'
exit 0
;;
*)
exit 0 # Default: show the normal approval prompt
;;
esac
```

This is useful for workflows where you want to pre-approve low-risk tools while still prompting for higher-risk operations.

### notification Hook

The `notification` hook is unique: it fires **asynchronously**, meaning the agent does not wait for it to finish before continuing work. It fires at key points in the session lifecycle:

- After a shell command completes
- When a permission prompt appears
- When an elicitation dialog is shown
- When the agent completes its response

Use `notification` for logging and alerting integrations that should not block the agent:

```json
{
"version": 1,
"hooks": {
"notification": [
{
"type": "command",
"bash": "./scripts/notify.sh",
"cwd": ".",
"timeoutSec": 10
}
]
}
}
```

> **Important**: `notification` hooks run in the background. Their exit code does **not** affect agent behavior — they cannot approve, deny, or block any action. Use them purely for observability and notifications.

### Plugin Hooks Environment Variables

When hooks are defined inside a **plugin**, the hook scripts receive two additional environment variables automatically:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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-04
estimatedReadingTime: '9 minutes'
tags:
- skills
Expand Down Expand Up @@ -35,6 +35,12 @@ Skills are folders containing a `SKILL.md` file and optional bundled assets. The
- Skills are **more normalised across coding agent systems** via the open [Agent Skills specification](https://agentskills.io/home)
- Skills still support **slash-command invocation** just like prompts did

### Built-in CLI Skills

Starting with v1.0.17, GitHub Copilot CLI ships with **built-in skills** that are available without any installation. These provide ready-made guidance for common tasks directly in the CLI. The first built-in skill covers [customizing the Copilot cloud agent's environment](../cli-for-beginners/) — helping you configure `.github/copilot-setup-steps.yml` and related setup.

You can browse and invoke built-in skills just like your own project skills. They serve as both useful capabilities and reference examples for writing your own.

### How Skills Differ from Other Customizations

**Skills vs Instructions**:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: 'Using the Copilot Coding Agent'
description: 'Learn how to use GitHub Copilot coding agent to autonomously work on issues, generate pull requests, and automate development tasks.'
authors:
- GitHub Copilot Learning Hub Team
lastUpdated: 2026-03-25
lastUpdated: 2026-04-04
estimatedReadingTime: '12 minutes'
tags:
- coding-agent
Expand Down Expand Up @@ -334,6 +334,34 @@ This repository provides a curated collection of agents, skills, and hooks desig

> **Example workflow**: Combine a `test-specialist` agent with a `database-migrations` skill and a linting hook. Assign an issue to the coding agent using the test-specialist agent — it will automatically pick up the migrations skill when relevant, and the hook ensures all code is formatted before completion.

## Critic Agent (Experimental)

GitHub Copilot CLI includes an experimental **Critic agent** that automatically reviews plans and complex implementations using a complementary AI model. Rather than relying on a single model to both generate and evaluate code, the Critic uses a separate model to independently critique the work — catching logical errors, missing edge cases, and implementation gaps earlier.

**How it works**:

```
1. Coding agent develops a plan or implementation
2. Critic agent reviews the work using a complementary model
3. Critique is fed back to the coding agent
4. Agent refines the plan or implementation
5. Final result is higher quality before you see the PR
```

**Key characteristics**:
- Available in **experimental mode** for Claude models only
- Activates automatically during complex plans and implementations — no manual invocation needed
- Runs transparently in the background as part of the agent's normal workflow
- Helps catch a category of errors that single-model systems miss (the "blind spot" of self-evaluation)

**Why it matters**: When the same model generates *and* evaluates its own code, it tends to miss the same classes of errors in both phases. The Critic agent's use of a complementary model introduces genuine independence — a design similar to code review by a second developer.

> **Note**: The Critic agent is an experimental feature. Check the [CLI release notes](https://github.com/github/copilot-cli/releases) for the latest status.

## Hooks and the Coding Agent

Hooks are especially valuable with the coding agent because they provide deterministic guardrails for autonomous work:
Expand Down