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 866c05157..e499c458d 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-06-25 +lastUpdated: 2026-07-10 estimatedReadingTime: '8 minutes' tags: - hooks @@ -390,7 +390,15 @@ Block dangerous commands before they execute. Use the `matcher` field to target } ``` -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. +The `preToolUse` hook receives JSON input with details about the tool being called. Your script can inspect this input and choose how to respond: + +| Exit code | Meaning | +|-----------|---------| +| `0` | **Approve** — allow the tool call to proceed | +| `2` | **Deny** *(v1.0.70+)* — explicitly block the tool call; the agent is told the tool was denied | +| other non-zero | **Error** — hook failed unexpectedly; the agent may retry or surface an error | + +> **Important (v1.0.70+)**: Use **exit code 2** to cleanly deny a tool call. Other non-zero exit codes signal an unexpected hook failure rather than a deliberate policy block. Updating existing deny scripts to use `exit 2` gives the agent a clearer signal and avoids confusing error messages. ### Modifying Tool Arguments with preToolUse @@ -642,7 +650,7 @@ echo "Pre-commit checks passed ✅" ## Best Practices - **Keep hooks fast**: Hooks run synchronously, so slow hooks delay the agent. Set tight timeouts and optimize scripts. -- **Use non-zero exit codes to block**: If a hook exits with a non-zero code, the triggering action is blocked. Use this for must-pass checks. +- **Use exit code 2 to block (v1.0.70+)**: For `preToolUse` hooks, exit with code `2` to cleanly deny a tool call. Other non-zero codes signal an unexpected error rather than a deliberate policy block. - **Bundle scripts in the hook folder**: Keep related scripts alongside the hooks.json for portability. - **Document setup requirements**: If hooks depend on tools being installed (Prettier, ESLint), document this in the README. - **Test locally first**: Run hook scripts manually before relying on them in agent sessions. 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 2afcc0eac..48238b515 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-07-06 +lastUpdated: 2026-07-10 estimatedReadingTime: '10 minutes' tags: - agents @@ -241,6 +241,28 @@ tools: ['codebase', 'terminal', 'postgres-mcp'] The agent can then query your database, analyze query plans, and suggest optimizations—all within the conversation. For setup details, see [Understanding MCP Servers](../understanding-mcp-servers/). +## Repository-Level Model and Effort Pinning (v1.0.70+) + +Beyond per-agent frontmatter settings, you can enforce a default model, reasoning effort level, and context tier across an entire repository using `.github/copilot/settings.json`. When a user opens the repository, these settings override their personal preferences — useful for ensuring all team members use an approved model and consistent quality settings: + +```json +{ + "model": "claude-sonnet-4", + "reasoningEffort": "medium", + "contextTier": "default" +} +``` + +This file is trusted only when folder trust is confirmed, so users who haven't explicitly trusted the repository won't have these settings applied. Supported keys: + +| Key | Description | Example values | +|-----|-------------|----------------| +| `model` | Default model for sessions in this repo | `"claude-sonnet-4"`, `"gpt-4.1"` | +| `reasoningEffort` | Default reasoning effort level | `"low"`, `"medium"`, `"high"` | +| `contextTier` | Default context window size | `"default"`, `"long_context"` | + +> **Tip**: Use this alongside per-agent `reasoningEffort` frontmatter for fine-grained control — the repo-level setting becomes the baseline, and individual agents can override it up or down as needed. + ## Best Practices ### Writing Effective Agent Personas 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 379ab5997..59fbfd3b3 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-06-30 +lastUpdated: 2026-07-10 estimatedReadingTime: '9 minutes' tags: - skills @@ -405,7 +405,12 @@ A: Yes, for clarity. Show examples of desired output format, patterns to follow, **Q: How do I review agent-proposed skill changes?** -A: In v1.0.66+, the agent can propose draft skill additions or improvements as it discovers reusable patterns during a session. Review each draft interactively with: +A: GitHub Copilot CLI can automatically discover reusable workflow patterns and propose new skills or improvements to existing ones. There are two ways this happens: + +- **Forge auto-detection** *(v1.0.70+)*: When Forge observes a clear, repeatable workflow pattern during a session, it automatically creates a draft skill proposal — no manual prompting required. +- **Manual review sessions** *(v1.0.66+)*: At any time, run `/chronicle skills review` to open an interactive review flow. + +Either way, proposed changes are held as drafts until you explicitly approve them: ``` /chronicle skills review diff --git a/website/src/content/docs/learning-hub/installing-and-using-plugins.md b/website/src/content/docs/learning-hub/installing-and-using-plugins.md index a45c85add..c74188487 100644 --- a/website/src/content/docs/learning-hub/installing-and-using-plugins.md +++ b/website/src/content/docs/learning-hub/installing-and-using-plugins.md @@ -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-06-24 +lastUpdated: 2026-07-10 estimatedReadingTime: '8 minutes' tags: - plugins @@ -184,7 +184,19 @@ Browse to the plugin via `@agentPlugins` in the Extensions search view or via ** ## Managing Plugins -Once installed, plugins are managed with a few simple commands: +### The /plugins Dashboard (v1.0.69+) + +From inside an interactive Copilot CLI session, the `/plugins` command opens a dashboard for managing your installed plugins without leaving the conversation: + +``` +/plugins +``` + +The dashboard lets you browse all installed plugins, enable or disable individual plugins, reload plugin extensions without restarting your session, and view plugin details like version and included components. This is the fastest way to troubleshoot a plugin or temporarily disable one that's causing issues. + +### Command-line Management + +Outside of an interactive session, use these commands to manage plugins: ```bash # List all installed plugins @@ -210,6 +222,21 @@ copilot --plugin-dir /path/to/my-plugin Plugins loaded this way appear in `/plugin list` under a separate **External Plugins** section, clearly distinguished from marketplace-installed plugins. This is useful for testing local plugins in development or loading private plugins that aren't published to any marketplace. +### Pinning Plugins to a Specific Commit (v1.0.70+) + +For reproducible environments, you can pin a plugin to an exact commit SHA so it never changes unexpectedly: + +```json +{ + "source": { + "repo": "github/awesome-copilot", + "sha": "a1b2c3d4e5f6..." + } +} +``` + +Add the `sha` field alongside the repository reference in your plugin source configuration. Pinned plugins won't be updated by `copilot plugin update` unless you explicitly change the SHA — giving you the same immutability guarantee you'd get from a lockfile. + ### Where Plugins Are Stored - **Marketplace plugins**: `~/.copilot/installed-plugins/MARKETPLACE/PLUGIN-NAME/`