Copilot Field Guide

How much control should I hand to the AI for this task, and which controls should I never hand over?

Not long ago, "using Copilot" meant typing a question into a chat box. Now Copilot can edit dozens of files, run your build, spawn helpers that work in parallel and open a pull request. Every one of those powers is optional. The skill this lab teaches is picking the right amount for each job, and writing down the rules that hold no matter how much you hand over.

You are the pilot in command. Copilot is the co-pilot.

Each part adds a layer. Part 1 is about how much autonomy to give, Part 2 about making it safe and on-brand, Part 3 about running a whole team of agents.

The weather app is where you feel the difference between autonomy levels. Ledgerly is where you watch a squad of agents do real, checkable work on code that looks fine: its four unit tests pass while the batch quietly loses money.

Ledgerly's pom.xml compiles with <maven.compiler.release>17</maven.compiler.release>, which a JDK 11 can't do. The squad's instructions also steer agents toward Java 17 idioms such as record. Any JDK from 17 up works; Temurin 21 is a good default. Check in VS Code's own terminal, because it can see a different JAVA_HOME from your system terminal:

java -version   # 17 or higher
mvn -v          # Maven 3.9+, and its "Java version" line also 17+

The model is the brain. The agent is the role it plays. The harness is the engine that runs the loop, applies permissions and calls tools.

• Model: a specific model, Auto (Copilot picks per request), or HydraFusion (a research preview that mixes models for you).
• Agent: Ask, Plan, Agent, or a custom agent like the Tech Lead. An agent is a persona plus a tool list plus, optionally, a model and hooks.
• Harness, chosen with Session Target: Local (VS Code's built-in loop, used all day today), Copilot (the runtime shared with Copilot CLI and the Copilot app), Claude and Codex (the vendors' own harnesses), and Cloud (runs remotely and comes back as a PR).

A model on its own only writes text. It can't open a file or run mvn. An agent works because the harness offers the model a menu of tools (read, search, edit, execute, start a subagent). When the model's reply is a request to use one, the harness checks the rules, runs it, and feeds the result back in. The loop repeats until the model answers in plain text.

Hooks, tool names and some customization features are harness-specific. A hook written for Local uses events like PreToolUse and fields like tool_name; the Copilot harness and Copilot CLI read the same .github/hooks/*.json files but have their own event list (agentStop, errorOccurred…). That is why the lab pins Session Target → Local.

A separate VS Code window built for assigning and reviewing agent work across many sessions, rather than chatting in one.

Open it with Open in Agents in the title bar or code --agents. It adds worktrees, Dev Containers, Automations (scheduled prompts), a Changes panel, Create PR and the experimental Agent merge. Sessions are shared with the normal Chat view, so you can start in one and finish in the other.

VS Code now ships every week (1.136 to 1.140 all landed in September 2026). Screens in any guide, including this one, drift quickly. Update on the morning of class with Help → Check for Updates, and when a menu doesn't match, search the Command Palette (⇧⌘P / Ctrl+Shift+P) for the command name.

• The whole context is re-sent every turn. In a 30-turn agent loop, the instructions and file contents from turn 1 are paid for again on turns 2 to 30. Prompt caching makes repeats cheaper, not free.
• Tool results pile up. Test logs, file reads and terminal output usually outweigh everything you typed.
• Every enabled tool costs tokens on every turn. Tool definitions are part of the fixed overhead, so an unused MCP server with 40 tools isn't free.
• Subagents multiply. Each one has its own context and its own bill. They are worth it when they keep noise out of the main thread, not by default.

Hover Ask in the agents dropdown and open its definition (or type /agents). It literally introduces itself as an agent ("You are an ASK AGENT…") and has only read-only tools. The built-in agents are examples of the same file format you'll use for the Tech Lead in Part 3.

/new in Ask scaffolds a whole project from a sentence and shows you a preview first. One bounded pass: it proposes, you accept or not. Nothing self-corrects. That's the point of the lowest rung.

An Agent turn can run 10 to 40 tool calls, rereading files and test output each time. An Ask turn that answers in one go uses a fraction of that. Under token billing, Ask with good context is often genuinely cheaper, not just "fewer prompts". Reach for Agent when the work needs doing, not just knowing.

More autonomy is not always better.

With Default Approvals, Agent asks before running terminal commands, and each request comes with an AI risk assessment that says what the command does in plain words ("executes remote code"). Read it. It's a second opinion, not a guarantee.

While an agent is working you can type a follow-up and choose how it lands.

• Steer injects your message into the run that's happening now. Use it to correct course ("make Celsius the default").
• Queue waits until the current turn finishes, then sends. Use it for the next task.
• Stop and send cancels the run and starts fresh with your message.

Typing # in chat lets you attach exactly the information the model needs, instead of hoping it goes looking for it.

Ask plus great context beats Agent plus vague context.

Select some code and press ⌘I / Ctrl+I. The suggestion appears in place, as a diff you accept or discard. It's the smallest and cheapest context there is: the selection, the file, and your one sentence. Perfect for a one-spot fix.

The context is everything the model sees on a turn. The context window is the most it can hold at once, measured in tokens.

A fresh chat "doesn't know" what you discussed in another chat, and a subagent doesn't know what its parent discussed with you, for the same reason: neither was in the context. If something must survive, it has to be written down somewhere that gets loaded, such as an instructions file, a skill or a plan file.

The small ring with a percentage at the bottom-right of the chat input is the context window control. Hover or click it.

1. System instructions: the agent's own prompt and tool definitions.
2. Custom instructions: copilot-instructions.md and matching *.instructions.md files, plus skill descriptions.
3. Conversation history: everything said so far, or a summary of it after compaction.
4. Implicit context: the open file, your selection, current errors, Git state.
5. Explicit references: what you attached with #.
6. Tool outputs: file reads, search results, terminal output, test logs.

The measurable drop in a model's quality as its input grows, even on simple tasks.

In Chroma's 2025 study of 18 frontier models, every model did worse as input length increased. Three things drive it:

• Lost in the middle. Models use information at the start and end of the context better than information buried in the middle. In a long session, your early instructions are the middle.
• Distractors. Similar-but-wrong content, such as an old stack trace or the previous version of a file, actively misleads.
• Weaker reasoning. Even when the model can find the right fact, it reasons over it less well in a long input.

• It forgets a rule it followed an hour ago.
• It reintroduces a bug it already fixed.
• It rereads the same files.
• It contradicts its own plan.
• It invents a file or method name.

These thresholds are a rule of thumb, not an official limit. Watch the behavior above, not just the number. VS Code also auto-compacts near the limit.

An agent that researches the codebase, asks clarifying questions, and writes a step-by-step plan before any code changes.

Run /plan …. It asks things like "hourly granularity, or every three hours?" and "which API endpoint?". The result is stored in session memory as plan.md (Chat: Show Memory Files). Then you choose Implement (normal approvals) or Start with Autopilot.

A plan file is externalized memory. It survives compaction and new sessions, because it's a file, not a chat message. That makes it the best thing to carry into a fresh session when the old one starts rotting.

Checkpoints are short-term AI undo. Git is long-term history.

Instructions and skills are suggestions the model usually follows. An agent's tool list and hooks are enforced by the harness: a Bug Hunter without the edit tool can't edit, however much it wants to, and a hook that denies git push wins every argument.

.github/copilot-instructions.md is added to every request in the workspace.

/init inspects your project and writes a first draft with build commands and conventions. Then edit it and add one rule your team really cares about, for example "Use java.time, never java.util.Date." Check it was used by expanding References under any reply.

Keep it short. Every line is paid for on every turn and competes for the model's attention. Ledgerly's says, among other things, "money is BigDecimal" and "do not add new dependencies".

Copilot decides whether to load a skill from its description alone, so write it like a search result that says what and when:

name: ascii-weather-art
description: Renders weather conditions as colorful ASCII-art banners in Java
  console output. Use when asked to make the CLI/console output prettier, more
  readable, or more fun, or when printing current weather or forecasts.

• Say what it does in the first clause, and when to use it after "Use when…".
• Use the words people actually type ("prettier", "console output"), not internal jargon.
• Every skill is also a slash command: /ascii-weather-art add a STORM test case.
• Same folder works in VS Code, Copilot CLI and the GitHub Copilot app. Personal skills live in ~/.copilot/skills/.

The hook file is only a pointer. All the logic lives in the script:

{
  "hooks": {
    "PreToolUse": [{
      "type": "command",
      "command": "bash .github/hooks/scripts/guardrails.sh",
      "windows": "powershell -NoProfile -ExecutionPolicy Bypass -File .github\\hooks\\scripts\\guardrails.ps1",
      "timeout": 10
    }]
  }
}

1. The harness pipes the pending tool call to the script as JSON on stdin: tool_name, tool_input, and so on.
2. The script checks it against its rules: rm -rf, git push, deploys, edits to .github/hooks.
3. To block, it prints a deny decision with a reason and exits with code 2. Exit 2 means "block, and tell the model why". The model reads the reason and adapts, usually to mvn clean instead of rm -rf target.

Debug them in the Output panel under GitHub Copilot Chat Hooks, and list discovered hook files with Chat: Configure Hooks or /hooks. Always test a hook in the harness you'll run it in.

Any agent with the agent tool (the built-in Agent has it) starts subagents when you ask. Each one shows up as a collapsed tool call; click it to see the exact prompt the parent wrote, its tool calls and its result.

Use three subagents in parallel to review src/main/java without editing anything:
one for calculation bugs, one for security issues, one for missing test coverage.
Then merge their findings into one table sorted by severity.

When a workflow is worth repeating, encode it. A coordinator and a worker are two .agent.md files:

Subagents can start their own subagents only if chat.subagents.allowInvocationsFromSubagents is on (off by default, up to five levels). Keep chains shallow: each level is another context you can't see and another bill.

Give every agent the smallest set of tools that lets it do its job, and nothing more.

The recon workers only get read and search. They can't edit, even if a confusing file or a prompt injection tells them to. Only the Test Engineer and the Tech Lead have edit, and the Tech Lead alone is meant to touch production code. If one agent goes wrong, the damage is limited to what it was allowed to do.

1. Recon, in parallel. The Tech Lead launches Bug Hunter, Security Auditor and Java Modernizer in one step. The timeline shows three 🤖 ┌ subagent START lines within a second or two. Each has a credit-usage pill.
2. Skills load. Expand a subagent: you'll see money-handling read and find-money-smells.sh run.
3. Red first. The Test Engineer writes tests that fail for the right reason and runs mvn -q test.
4. Green. The Tech Lead fixes the production code.
5. Quality gate. If it tries to finish while tests are red, the Stop hook says no: 🔁 quality gate RED, and it keeps working.
6. Handoff. Two buttons: independent review, or draft the PR.

Writing the failing test first proves two things the final green run can't: that the bug is real, and that the test would catch it if it came back. A test written after the fix might pass for the wrong reason. Kent Beck popularized this as red, green, refactor in Test-Driven Development: By Example (2002).

The Code Reviewer has disable-model-invocation: true, so the Tech Lead can't call it as a subagent. It isn't marking its own homework. For a truly independent opinion, pin it to a different model family with model:.

Three of the five bugs come from treating money as a double. The squad's money-handling skill writes down the rules: BigDecimal built from strings, an explicit scale, RoundingMode.HALF_EVEN, lossless splits, and currency kept next to the amount (record Money(BigDecimal amount, Currency currency)).

In the Chat view use … → Show Agent Debug Logs, or run Developer: Open Agent Debug Logs. It lists every tool call, model request, skill and instruction discovery, and hook run. The Agent Flow Chart draws the coordinator fanning out to subagents, with tokens and seconds per step. The Summary totals tool calls, tokens, errors and duration.

/troubleshoot Which subagents ran in parallel, how many tokens did each use, and did the Bug Hunter load the money-handling skill?

The Chat Debug view (/debug) shows the raw prompt: find your skills list, instructions and the SessionStart context in it.

cat .github/hooks/logs/timeline.log
jq -r 'select(.event=="PreToolUse") | .payload.tool_name' \
   .github/hooks/logs/audit.jsonl | sort | uniq -c | sort -rn
git diff demo-start --stat

The hook logs are yours: they don't depend on any experimental setting, and you control what's in them. Git is the final word on what changed.

copilot          # start in this folder
/agent           # pick Tech Lead
/fleet           # let the CLI fan out parallel subagents itself
/tasks           # watch running subagents and shell commands
/usage           # tokens and credits
/share           # export the session to Markdown or a gist
copilot --log-level debug --log-dir ./copilot-logs

The CLI uses the Copilot harness, so hook events and payloads differ from Local. Treat it as an experiment until you've tested your hooks there.

• Agents window → New session → Worktree runs the squad in a separate folder on its own branch, so your working copy stays untouched. Review the diff in Changes, then Create PR.
• Cloud (/delegate in the CLI, or Session Target → Cloud) runs on GitHub's machines and comes back as a PR. Agent-scoped hooks are Local-only, so cloud runs rely on the repo's .github/hooks and your PR checks.

java -version && mvn -v                                  # 17+ and 3.9+
mvn -q test && mvn -q compile && java -cp target/classes com.ledgerly.payments.App
scripts/setup-demo.sh          # Windows: scripts\setup-demo.ps1 — git repo + demo-start tag
scripts/watch-timeline.sh      # live hook timeline
scripts/reset-demo.sh          # back to the buggy start
git diff demo-start --stat     # what the squad changed
code --agents                  # open the Agents window

---
name: Bug Hunter
description: Read-only specialist that finds functional and money bugs.
user-invocable: false            # worker: hidden from the dropdown
tools: ['read', 'search']        # least privilege: can't edit
# model: ['Claude Haiku 4.5']    # cheap model for recon
---
You are a meticulous banking QA engineer. Do not edit files.
Return a Markdown table: | # | Severity | File:line | Problem | Example | Fix |

.github/skills/<name>/
├── SKILL.md        ---
│                   name: <name>
│                   description: <what it does>. Use when <trigger words>.
│                   ---
│                   <steps, loaded only on match>
└── references/     <loaded only if SKILL.md points to it>