mirror of
https://github.com/github/awesome-copilot.git
synced 2026-04-11 10:45:56 +00:00
docs: add permissionRequest hook and built-in CLI skills to Learning Hub
- automating-with-hooks.md: Add new permissionRequest hook event to the events table, with an explanatory note and a practical example showing how to programmatically approve or deny tool permission requests in CI and automated environments (introduced in CLI 1.0.16) - creating-effective-skills.md: Add a 'Built-in CLI Skills' section documenting that CLI 1.0.17 ships with built-in skills pre-installed, how to list them, and how they complement community and personal skills Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
committed by
GitHub
parent
5f3d66c380
commit
faf82b6fae
@@ -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-03
|
||||
estimatedReadingTime: '8 minutes'
|
||||
tags:
|
||||
- hooks
|
||||
@@ -90,6 +90,7 @@ Hooks can trigger on several lifecycle events:
|
||||
| `sessionStart` | Agent session begins or resumes | Initialize environments, log session starts, validate project state |
|
||||
| `sessionEnd` | Agent session completes or is terminated | Clean up temp files, generate reports, send notifications |
|
||||
| `userPromptSubmitted` | User submits a prompt | Log requests for auditing and compliance |
|
||||
| `permissionRequest` | Agent requests permission to take an action | **Programmatically approve or deny** permission requests, auto-approve trusted action categories in CI/automation |
|
||||
| `preToolUse` | Before the agent uses any tool (e.g., `bash`, `edit`) | **Approve or deny** tool executions, block dangerous commands, enforce security policies |
|
||||
| `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 |
|
||||
@@ -101,6 +102,8 @@ Hooks can trigger on several lifecycle events:
|
||||
|
||||
> **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.
|
||||
|
||||
> **New in 1.0.16**: The `permissionRequest` hook is a companion to `preToolUse` that fires when the agent requests permission for an action at the permission-prompt level, before the tool is invoked. Use it to programmatically approve trusted action categories in CI and automation pipelines without human interaction.
|
||||
|
||||
### sessionStart additionalContext
|
||||
|
||||
The `sessionStart` hook supports an `additionalContext` field in its output. When your hook script writes JSON to stdout containing an `additionalContext` key, that text is **injected directly into the conversation** at the start of the session. This lets hooks dynamically provide environment-specific context—such as the current git branch, deployment environment, or team onboarding notes—without requiring the user to paste it manually.
|
||||
@@ -207,6 +210,51 @@ automatically before the agent commits changes.
|
||||
|
||||
## Practical Examples
|
||||
|
||||
### Programmatic Permission Approval with permissionRequest
|
||||
|
||||
The `permissionRequest` hook fires when the agent requests permission to take an action — before the agent's permission prompt is shown to the user. Use it to auto-approve certain categories of actions in CI and automation environments, or to implement policy-based controls over what the agent is allowed to do:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"hooks": {
|
||||
"permissionRequest": [
|
||||
{
|
||||
"type": "command",
|
||||
"bash": "./scripts/approve-or-deny-permission.sh",
|
||||
"cwd": ".",
|
||||
"timeoutSec": 5
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The hook receives JSON input describing the requested action. Your script can exit `0` to approve the request, or non-zero to deny it. This is particularly useful in:
|
||||
|
||||
- **CI pipelines**: Auto-approve read-only actions (file reads, searches) while denying write operations.
|
||||
- **Governance environments**: Enforce a policy that logs and approves only pre-defined action categories.
|
||||
- **Automated workflows**: Allow the agent to run without interactive prompts for well-understood tasks.
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# approve-or-deny-permission.sh
|
||||
# Auto-approve read-only actions; deny everything else
|
||||
|
||||
INPUT=$(cat)
|
||||
TOOL=$(echo "$INPUT" | jq -r '.tool // empty')
|
||||
|
||||
case "$TOOL" in
|
||||
read|search|glob|grep|list_dir)
|
||||
exit 0 # Approve read-only tools
|
||||
;;
|
||||
*)
|
||||
echo "Permission denied for tool: $TOOL" >&2
|
||||
exit 1 # Deny anything that modifies state
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
### Handling Tool Failures with postToolUseFailure
|
||||
|
||||
The `postToolUseFailure` hook fires when a tool call fails with an error — distinct from `postToolUse`, which only fires on success. Use it to log errors, send failure alerts, or implement retry logic:
|
||||
|
||||
@@ -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-03
|
||||
estimatedReadingTime: '9 minutes'
|
||||
tags:
|
||||
- skills
|
||||
@@ -35,6 +35,16 @@ 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 GitHub Copilot CLI **1.0.17**, the CLI ships with a set of **built-in skills** that are available immediately after installation — no setup required. These skills cover common tasks like customizing the Copilot coding agent's environment. To discover what built-in skills are available, list them from within a session:
|
||||
|
||||
```
|
||||
/skills list
|
||||
```
|
||||
|
||||
Built-in skills work exactly like your own project or personal skills — agents can discover and invoke them automatically, or you can invoke them manually with their `/command` name. They complement the community skills in this repository and the skills you create yourself.
|
||||
|
||||
### How Skills Differ from Other Customizations
|
||||
|
||||
**Skills vs Instructions**:
|
||||
|
||||
Reference in New Issue
Block a user