DEV Community: Daniel Diaz

Your agent follows instructions. Until it doesn't.

Daniel Diaz — Tue, 19 May 2026 19:08:52 +0000

Hooks over flowers

Instructions suggest. Skills guide. Hooks enforce.

That's the whole story, but it took me a while to understand why it matters.

You've set up your agent well. Custom instructions for coding standards. Skills for your team's specific patterns. Copilot knows your stack, follows your conventions, generates code that looks like yours.

Then one day it decides to run rm -rf dist/ before rebuilding. Or it edits a file and moves on without running the formatter. Or it completes a task without touching the test suite. All technically valid moves. All not what you wanted.

The problem isn't instructions or skills failing. It's that they guide the agent. They inform its decisions. But an agent that's informed can still decide differently. Instructions are context. They're not guarantees.

Hooks are guarantees.

What are Agent Hooks?

Agent Hooks are shell commands that VS Code runs at specific lifecycle points during an agent session. Not suggested. Not requested. Run.

They live in your repo at:

.github/
└── hooks/
    └── hooks.json

The filename can be anything. VS Code loads all *.json files inside .github/hooks/.

A hook that auto-formats every file the agent edits looks like this:

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

Save the file. VS Code picks it up automatically. The next time the agent edits any file, Prettier runs. No prompt needed, no skill invocation, no agent cooperation required.

VS Code added agent-scoped hooks in version 1.111 (March 2026). Workspace hooks via .github/hooks/ were available earlier. Use /create-hook in chat to scaffold a hook configuration.

Meet the eight

This is where hooks get interesting. VS Code exposes eight points in an agent session where your code can run:

Event	When it fires	What you can do
`SessionStart`	User submits the first prompt	Inject context, validate project state
`UserPromptSubmit`	User submits any prompt	Audit requests, add system context
`PreToolUse`	Before the agent invokes any tool	Block dangerous operations, require approval
`PostToolUse`	After a tool completes	Run formatters, trigger follow-up actions
`PreCompact`	Before conversation context is compacted	Export state before it gets truncated
`SubagentStart`	A subagent is spawned	Initialize subagent resources
`SubagentStop`	A subagent completes	Aggregate results, clean up
`Stop`	Agent session ends	Run tests, generate reports, send notifications

Most people, when they first hear about hooks, think PostToolUse: run a formatter. That's valid and immediately useful.

But look at PreToolUse. That's where you can stop the agent before it does something.

And SessionStart. That's where you can inject context that the agent doesn't have yet: current branch, environment, version, whether production deploys are frozen.

PreCompact is the one nobody talks about. When a long session gets too big for the context window, VS Code compacts it. You can hook into that moment to export state, save important context to a file, or log what's about to be truncated.

Stop. Before anything happens

PreToolUse fires before every tool invocation. Your hook receives the tool name and its input via stdin as JSON:

{
  "hookEventName": "PreToolUse",
  "tool_name": "run_in_terminal",
  "tool_input": { "command": "rm -rf dist/" }
}

Your hook can return one of three permissionDecision values:

"allow": proceed without asking the user
"deny": block the operation entirely
"ask": stop and require explicit user confirmation

A simple shell script that blocks destructive commands:

#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command // ""')

if echo "$command" | grep -qE '(rm -rf|DROP TABLE|git push --force)'; then
  echo '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Destructive command blocked by policy"}}'
  exit 0
fi

echo '{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow"}}'

Wire it up:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-command.sh"
      }
    ]
  }
}

The agent never sees the operation. It doesn't try to negotiate. The hook returns deny, the tool call stops.

There's also a simpler way to block without writing any JSON at all. Every script, when it finishes, returns a number to whoever called it. That's an exit code. 0 means success. VS Code specifically watches for exit code 2 as a "stop this right now" signal. You just write your reason to stderr and exit:

echo "Production deploys are frozen" >&2
exit 2

VS Code passes that message to the model as context and blocks the tool call. No JSON, no hookSpecificOutput, no ceremony.

One more thing worth knowing: continue: false in the JSON output stops the entire agent session, not just one tool call. Think of exit code 2 as hitting the brakes on a single operation. continue: false is turning off the engine. Use the second one carefully.

If you define more than one hook for the same event, VS Code runs all of them. When multiple PreToolUse hooks return conflicting permissionDecision values, the most restrictive wins: deny beats ask, and ask beats allow. You can stack a validation hook and a logging hook on the same event without worrying about one canceling the other.

Full protocol reference: Hook input and output, VS Code docs

The morning briefing

Instructions are static. They were written at the time you created the file. But some context only exists at runtime: the current git branch, which environment is active, whether the CI pipeline is currently broken.

SessionStart fires before the agent does anything. Your hook can inject that information directly into the session:

#!/bin/bash
branch=$(git branch --show-current)
node_version=$(node -v)
env_name=${NODE_ENV:-development}

jq -n \
  --arg branch "$branch" \
  --arg node "$node_version" \
  --arg env "$env_name" \
  '{
    hookSpecificOutput: {
      hookEventName: "SessionStart",
      additionalContext: ("Branch: " + $branch + " | Node: " + $node + " | Env: " + $env)
    }
  }'

Every session the agent starts, it already knows what branch it's on and what environment it's working in. No need to tell it.

Not every hook is for everyone

Workspace hooks apply to every agent interaction. But sometimes you want a hook that only runs for a specific agent.

Since VS Code 1.111, you can define hooks directly in a custom agent's frontmatter. The hooks field here uses YAML syntax because it lives inside the .agent.md frontmatter, but the structure maps directly to what you'd write in a JSON config file.

---
name: "PM Explainer"
description: "Explains to your PM why it's taking longer. Also formats code."
hooks:
  PostToolUse:
    - type: command
      command: "./scripts/format-and-lint.sh"
---

You are a code editing agent. After making changes, files are formatted and linted automatically.

Enable chat.useCustomAgentHooks to use this. The hook only runs when this specific agent is active, either selected by the user or invoked as a subagent.

The part everyone skips (don't)

Hooks run shell commands with the same permissions as VS Code. That's the power and the responsibility.

Before enabling hooks from any source, read the scripts. Hooks receive JSON input from the agent. Validate and sanitize that input before using it. Never hardcode secrets in hook scripts; use environment variables.

One specific risk: if the agent has access to edit scripts that your hooks run, it can modify those scripts during a session and execute code it writes. Use chat.tools.edits.autoApprove to prevent the agent from editing hook scripts without manual approval.

When your hook does nothing

If a hook runs but nothing seems to happen, check the GitHub Copilot Chat Hooks output channel. Open the Output panel in VS Code, select that channel from the list, and you'll see which hooks were loaded, which fired, their exit codes, and any stdout or stderr output.

Hook scripts that exit with code 1 produce a non-blocking warning: the agent continues, but the issue shows up in the channel. Exit code 2 is the one that blocks and surfaces the message to the model. If your hook is supposed to stop something and it isn't, check which exit code your script is returning.

Already have Claude hooks? You're closer than you think

If you're coming from Claude Code, VS Code reads hook configurations from .claude/settings.json and .claude/settings.local.json by default. The format is the same, with two differences to watch for:

Tool input property names: Claude Code uses snake_case (e.g. tool_input.file_path), VS Code uses camelCase (e.g. tool_input.filePath)
Tool names: different. Claude uses Write/Edit, VS Code uses create_file/replace_string_in_file

Where Hooks Fit

Hooks are the third piece of a larger customization system:

Instructions (copilot-instructions.md / .github/instructions/): always-on context. Good for project-wide rules.
Skills (.github/skills/): domain-specific, activated on demand. Good for encoding your conventions.
Hooks ← you're here: deterministic automation at lifecycle points. Good for guarantees.
MCP Servers: external tools: database access, browser automation, external APIs.
Plugins: installable bundles that package all of the above together.

Instructions tell the agent how to work. Skills tell the agent what patterns to follow. Hooks make sure certain things happen regardless of what the agent decides.

They're not interchangeable. They're complementary.

Takeaways

The difference between guidance and guarantee matters.

Instructions and skills are probabilistic. They shift the agent's behavior in the right direction. Hooks are deterministic. Your code runs, period. Both have their place. Knowing which to reach for is the skill.

Start with one hook.

One PostToolUse Prettier hook that auto-formats on every file edit. Ship it, live with it for a week, see what else you want to automate. The scope expands naturally.

This is the second post in a series on VS Code agent customizations: Skills, Hooks, MCP Servers, CLI, and Plugins.

Previous post: I stopped fighting Copilot's conventions. I taught it mine instead.

Official docs: Agent Hooks (VS Code)

Stop getting generic output from Copilot. Teach it your patterns.

Daniel Diaz — Thu, 23 Apr 2026 13:11:44 +0000

The Problem

You use Copilot. You ask it to build something, and it does sort of. It follows your prompt, generates working code, and you ship it.

Then you do it again the next day. And the day after.

A month later, your codebase has class names in PascalCase next to camelCase functions, three different error handling styles, two ways to structure the same kind of module, and hooks that work differently from each other for no clear reason.

All of it generated by Copilot. All of it reviewed and accepted by you.

The problem isn't that Copilot generates bad code. It generates generic code. It doesn't know your stack, your team's decisions, or the patterns you settled on six months ago. It works from its training data. And your codebase slowly starts to look like it was written by the internet.

What are Agent Skills?

Agent Skills are Markdown files that tell Copilot what your conventions are, for a specific domain, task, or workflow. Persistent context the agent reads before generating anything in that area.

They live in your repo at:

.github/
└── skills/
    └── your-skill-name/
        └── SKILL.md

That's the entire setup. No config files, no registration, no CLI step. The file being there is enough for VS Code to discover it.

When you mention the skill in a chat prompt like "Use the component-structure skill to create a new button", Copilot reads that SKILL.md first, then generates code that follows your conventions.

This is what separates skills from regular prompts: they're reusable, versioned, and shared through the repo. Your conventions stop living in someone's head or a doc nobody reads; they live next to the code they govern.

With a well-written description, Copilot can automatically load the relevant skill based on your request without explicit mention. Explicitly referencing skills is more common with smaller models that need extra guidance to identify the right context.

VS Code added native skill support and the /create-skill command in version 1.110. In version 1.113, a dedicated Chat Customizations editor was added, providing a centralized UI to manage skills, instructions, and agents from a single place.

A minimal SKILL.md

Here's the minimum a skill needs to actually work:

.github/skills/component-structure/SKILL.md

Frontmatter:

---
name: component-structure
description: Guidelines for creating React components following team conventions: named exports, props interface, no inline JSX logic.
---

Body:

# Component Structure Skill

## When to use
Creating new React components or reviewing component patterns.

## Conventions
- One component per file
- Props interface defined above the component
- Named exports only (no default exports)
- No inline logic in JSX, extract to handlers or custom hooks
- Error boundaries at page level, not inside components

## Never do this
- Default exports
- Logic directly in JSX
- Props without an explicit interface

Pattern example:

interface ButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;
}

export function Button({ label, onClick, disabled = false }: ButtonProps) {
  const handleClick = () => {
    if (!disabled) onClick();
  };

  return (
    <button onClick={handleClick} disabled={disabled}>
      {label}
    </button>
  );
}

The name field must match the directory name exactly. The description is what Copilot reads to decide whether to load the skill, so be specific. Full frontmatter reference: SKILL.md file format.

Four sections. One pattern. A few explicit don'ts.

When Copilot reads this before generating a component, it follows the same structure every time not because it guessed right, but because you told it.

The skill doesn't need to be exhaustive. It needs to be specific. A skill that covers one thing well beats one that tries to cover everything and ends up covering nothing.

Creating a skill from a conversation

One of the more useful additions in VS Code 1.110 is /create-skill. After debugging a problem across several chat turns and landing on the right approach, you type:

/create-skill

The agent extracts the pattern from your conversation and scaffolds a SKILL.md for you. You review, adjust, commit.

This is how skills actually get created in practice. You don't design a skill from scratch. You solve a problem, recognize you'll solve it the same way every time, and capture that. /create-skill removes the friction of doing the capture manually.

The Ecosystem

Skills are one piece of a larger customization system. Here's a quick map:

Instructions (copilot-instructions.md / .github/instructions/): always-on context loaded in every session. Good for project-wide rules.
Skills ← you're here: domain-specific, activated on demand when mentioned in chat.
Hooks: scripts that run at specific points in the agent lifecycle: before a response, after a file write, on session start.
MCP Servers: external tools that give the agent capabilities your codebase doesn't have natively, like database access, browser automation, or external APIs.
Plugins: installable bundles that package all of the above together.

Each of these has its own post coming. Skills are the easiest starting point entirely local to your repo, zero infrastructure, and the effect on the agent is immediate.

What I Learned

The model doesn't know your stack. You have to teach it.

Copilot is trained on public code. Your team's specific decisions aren't in that data. Skills are the mechanism for closing that gap.

One good skill beats ten prompts.

A well-written skill invoked consistently produces better results than re-explaining your conventions in each prompt. The repeatability is the point.

The skill itself is documentation.

Writing a SKILL.md forces you to articulate things that previously existed informally. Once it's committed, the team has a shared reference, not just for Copilot.

The real value shows up at review time.

When everyone uses the same skill, code review stops being about style. You argue about logic instead. That's the conversation worth having.

This is the first post in a series on VS Code agent customizations: Skills, MCP Servers, CLI, Hooks, and Plugins.

Official docs: Agent Skills VS Code