Skip to content
Draft
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
15 changes: 13 additions & 2 deletions 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-07-13
lastUpdated: 2026-07-23
estimatedReadingTime: '8 minutes'
tags:
- hooks
Expand Down Expand Up @@ -94,7 +94,7 @@ Hooks can trigger on several lifecycle events:
| `postToolUse` | After a tool **successfully** completes execution | Log results, track usage, format code after edits |
| `postToolUseFailure` | When a tool call **fails with an error** | Log errors for debugging, send failure alerts, track error patterns |
| `PermissionRequest` | When the CLI shows a **permission prompt** to the user | Programmatically approve or deny permission requests, enable auto-approval in CI/headless environments |
| `agentStop` | Main agent finishes responding to a prompt | Run final linters/formatters, validate complete changes |
| `agentStop` | Main agent finishes responding to a prompt | Run final linters/formatters, validate complete changes. Receives `stop_hook_active=true` when the CLI is forcing a stop after repeated blocks (v1.0.72+) |
| `preCompact` | Before the agent compacts its context window | Save a snapshot, log compaction event, run summary scripts |
| `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 |
Expand Down Expand Up @@ -369,6 +369,17 @@ Run ESLint after the agent finishes responding and block if there are errors:

If the lint command exits with a non-zero status, the action is blocked.

> **Loop protection (v1.0.72+)**: If an `agentStop` hook repeatedly blocks the agent, the CLI ends the turn after 8 consecutive blocks to prevent infinite loops. When this happens, the hook receives a `STOP_HOOK_ACTIVE=true` environment variable (and a `stop_hook_active: true` field in the JSON input). Use this flag to self-limit — for example, skip expensive validation steps when the CLI is forcing a stop:
>
> ```bash
> #!/usr/bin/env bash
> if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
> echo "Forced stop — skipping full lint." >&2
> exit 0 # Allow the stop to proceed
> fi
> npx eslint . --max-warnings 0
> ```

### Security Gating with preToolUse

Block dangerous commands before they execute. Use the `matcher` field to target only the `bash` tool, so the hook doesn't fire for file edits or other tools:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -381,6 +381,13 @@ copilot skill add https://example.com/skill.zip # add a skill from a URL
copilot skill remove my-skill # remove an installed skill by name
```

You can also install skills via the plugins system (v1.0.72+), which supports installing from a file, URL, or directory with an optional `--scope project` flag to install into the current repository:

```bash
copilot plugins install --skill ./my-skill/
copilot plugins install --skill ./my-skill/ --scope project
```

You can also run `/skill` (or the existing `/skills`) inside an interactive session to see what's loaded. The `copilot skill` subcommand is the recommended way to install skills that aren't packaged inside a plugin.

**Q: How are skills different from prompts?**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: 'Installing and Using Plugins'
description: 'Learn how to find, install, and manage plugins that extend GitHub Copilot CLI with reusable agents, skills, hooks, and integrations.'
authors:
- GitHub Copilot Learning Hub Team
lastUpdated: 2026-07-13
lastUpdated: 2026-07-23
estimatedReadingTime: '8 minutes'
tags:
- plugins
Expand Down Expand Up @@ -204,6 +204,23 @@ Or from an interactive session:

Browse to the plugin via `@agentPlugins` in the Extensions search view or via **Chat: Plugins** in the Command Palette, then click **Install**.

### Installing Individual Skills (v1.0.72+)

You can install a single skill — without packaging it as a plugin — directly from a file, URL, or directory:

```bash
# Install a skill from a local directory
copilot plugins install --skill ./my-skill/

# Install a skill from a URL (e.g., a zip archive)
copilot plugins install --skill https://example.com/my-skill.zip

# Install into the current repository's .github/skills/ directory
copilot plugins install --skill ./my-skill/ --scope project
```

Installed skills appear in `copilot skill list` and are immediately available for use. This is useful when you want a single skill from a repository without installing the full plugin that contains it.

## Managing Plugins

Once installed, plugins are managed with a few simple commands:
Expand Down