Bring the agent loop to your terminal with the Copilot CLI, then stop re-typing your rules: make them reusable with instructions, prompt files, custom agents, and skills, placed at the right scope.
What you'll learn
Control the Copilot CLI loop and prove determinism before automating
Choose the narrowest customization layer that owns a behavior
Place a rule at repository, organization, or CLI scope correctly
Tell prompt files, custom agents, and agent skills apart by their job
Once agent mode feels familiar, the terminal is an obvious next stop. Start the Copilot CLI with copilot and you get the same working loop: it proposes, you approve, and the result still needs verification.
The terminal makes two shortcuts especially tempting. You can script or schedule a prompt before you know whether it behaves consistently. You can also keep typing the same project rules into every session. Handle them in that order. First prove the loop under supervision. Then move stable rules and procedures into the customization layer that actually owns them.
The CLI brings agents to the terminal
The Copilot CLI is a distinct, standalone product (not the older gh copilot extension) that brings the same controlled loop to the command line: state a goal, give context, require a plan before edits, inspect each proposed operation, review the diff, and run the narrowest check that proves the outcome. File changes require your explicit approval, and approving a command still isn't the same as verifying its result.
Where the CLI opens up is how you invoke it. An interactive session is a terminal conversation you steer in real time, the right choice whenever the task needs judgment. Programmatic use submits a fixed prompt from another process and captures the response. The CLI exposes flags for exactly this, including a non-interactive mode and a switch that suppresses extra usage output so a script receives clean text. Scheduled use repeats a prompt on an interval, and a GitHub Actions workflow runs the automation in GitHub's environment. Each step away from interactive raises the stakes, because the same mistake can now recur with no one watching.
Prove determinism before you automate. Before you schedule a task or move it into Actions, run the identical prompt twice against an unchanged repository and compare the outputs byte for byte. If they differ, or if one invents a value the source never contained, the task isn't ready to run unattended. Tighten its source boundary, output format, and missing-value rule until two runs agree. Automation should follow demonstrated determinism, never precede it. When you want an audit trail, the CLI's session record (its "chronicle") is useful evidence of what the agent attempted, but reconcile it against your actual version-control status and diff. A transcript is never a substitute for inspecting the change.
Prove it's deterministic before you schedule it
Run the same prompt twice on an unchanged repository and compare the results before you ever move a task into a schedule or a GitHub Actions workflow. If the two outputs differ, or one fabricates a missing value, the task is not ready to run unattended. A mistake that recurs with nobody watching is far more expensive than one you catch live.
Start a CLI session read-only· github-copilot
Bad example
Look through this repo and tell me what it uses and how to test it.
Good example
Inspect the current repository without modifying anything. Report the top-level files, the detected language or framework, the likely test command, and any repository instruction files. Cite a file path for each conclusion. If you cannot determine something, write "Not determined."
Why this works: A grounded snapshot of the repo with a path behind every claim, and no files changed, which you confirm with your version-control status.
Pick the right customization layer
Customization saves a stable rule or procedure from being retyped in every session. The editor and CLI provide several places to put it. Choose the smallest layer that can own the behavior without help from another copy:
Layer
Use it for
Instructions
Persistent project or user rules ("never edit generated files")
Prompt file
A repeatable request with explicit inputs
Custom agent
A specialized role with a stable decision policy and guardrails
Agent skill
A complete, multi-step procedure a task can reuse
Hook
Automation triggered by an event
MCP server
External tools or data exposed to the agent
Plugin
A packaged bundle of the above
Use instructions for broad rules and a prompt file for a recurring request. A custom agent suits a distinct role, while a skill carries a complete procedure. Add an MCP server only when the work needs an external tool or data source. If the same behavior appears in four layers, you now have four copies that can disagree.
GitHub's Customization Library offers examples to study. Its mid-2026 census contained nineteen: nine custom instructions, six prompt files, and four custom agents. Adapt their patterns to your repository. A pasted example cannot know your actual files, risks, or vocabulary.
Pick the narrowest primitive that owns the behavior
Before you build a custom agent or a skill, ask whether a plain instruction or a prompt file already covers the need. The narrowest layer that fully owns a behavior is the easiest to test and the least likely to duplicate a rule that lives elsewhere and drifts out of sync.
A prompt file with explicit inputs· github-copilot
Bad example
Write a reusable prompt that explains code to a new developer.
Good example
Explain a specific code target for a developer new to this repository. Required inputs from me: an exact file path, and a symbol or line range. Before answering, inspect the named target, separate observed behavior from assumptions, and record unavailable facts instead of guessing. Return these sections: Purpose, Execution flow, Dependencies and data, Edge cases and risks, Verification questions.
Why this works: A repeatable explanation request that always demands an exact target and always separates fact from guess. Save it as a .prompt.md file and reuse it.
Instructions live at three scopes
Custom instructions are persistent background guidance, distinct from a prompt: the instruction says "HTTP handlers must call a service, not query the database," while the prompt says "add an endpoint returning stock for one SKU." Instructions shape a response. They don't enforce correctness. Tests, review, and access controls remain your evidence that a change is acceptable.
Instructions live at three scopes, and matching content to scope is most of the skill. The repository scope has a documented target, .github/copilot-instructions.md, that travels with the code, so reviewers inspect it alongside the change. The organization scope holds a technology-neutral baseline shared across repositories. The Copilot CLI scope holds rules for terminal work. A clean way to sort a rule is to ask whether it stays true across two repositories with different stacks. If yes, it's an organization baseline (for example, "never put credentials in prompts or instructions"). If it names this project's directories, framework, or commands, it belongs in repository instructions. If it's a one-time outcome, it stays in the prompt.
Honest instructions come from two habits. First, write observable rules: a rule should name a directory, boundary, file, command, output field, or condition you can inspect, so "keep HTTP handlers thin, route database access through the existing repository layer" beats "keep the architecture clean." Second, test one surface at a time and record which one you tested. An editor, GitHub.com, and the CLI don't necessarily load the same file with the same precedence, so a result on one surface doesn't prove behavior on another. When two scopes would say different things, rewrite them to agree rather than betting on an unverified precedence order.
Rewrite a vague rule as an observable one· github-copilot
Bad example
Rewrite this instruction so it is clearer: keep the architecture clean.
Good example
Here's a draft custom instruction I was about to save: "[paste your vague rule, e.g. keep the architecture clean]." Rewrite it as an observable rule that names a directory, boundary, file, command, or output field I can inspect in a plan, diff, or command result. Then show how a reviewer would check whether a change actually followed it.
Why this works: A rule you can verify (for example, "keep HTTP handlers out of the data layer, route through the existing repository module") plus the concrete check that proves compliance.
Prompt files, agents, and skills
These three are easy to confuse because they overlap, so anchor each to the question it answers. A prompt file (.prompt.md) answers "what repeatable request do I want to make?": a template with explicit inputs, so instead of trusting an implicit editor selection you name the exact file and symbol or range. A custom agent (.agent.md) answers "which specialist should lead this?": a named role with a stable inspection policy and guardrails that persist across the conversation, unlike a one-shot prompt. An agent skill (SKILL.md) answers "what complete procedure should be available?": a self-contained playbook with steps, stop conditions, and a checkable output.
Take one repository need, "keep endpoint documentation accurate," and watch it split. As a rule ("never document a field you can't verify in the repo"), it's a custom instruction. As a request ("given this route file and symbol, document it under these headings"), it's a prompt file. As a specialist ("act as an API-doc reviewer, inspect evidence before proposing changes, and never edit application code"), it's a custom agent. As a procedure ("locate the route, its schemas, authorization, validation, tests, and examples, compare them, then produce documentation and a verification checklist"), it's a skill. Same need, four different owners.
Whichever you build, keep it evidence-first: have the customization inspect real files, separate observed behavior from assumptions, and label anything it can't verify instead of inventing a plausible field or status code. A common layout stores these under your repository: prompt files in a prompts folder, custom agents in an agents folder, and skills each in their own folder with a SKILL.md. Exact discovery can vary by version, so if a saved file won't invoke, paste its body into chat to test the content, and don't confuse that with proving discovery worked.
Test the content, not the plumbing
If a saved prompt file, custom agent, or skill won't invoke through the interface, paste its body straight into chat and run it. That isolates whether the content is good from whether native discovery worked: two different problems. Never claim a customization "loaded" when all you verified was that its instructions produce a good answer.
Define a read-only specialist· github-copilot
Bad example
Create a README specialist agent for this repository.
Good example
Act as a README specialist for this repository. Before drafting anything, inspect the repository tree, entry points, scripts, tests, and configuration, and list the facts you could not verify. When you propose README content, describe only commands that appear in repository evidence, keep prerequisites, setup, usage, and testing separate, and label any missing fact explicitly. Do not change application code. First report facts verified, facts missing, and the sections you recommend.
Why this works: An evidence-first specialist whose guardrails persist across the conversation: the pattern you'd freeze into a custom agent (.agent.md) once it behaves.
Try it yourself
Make one rule reusable and prove it loaded
In a disposable branch, turn a project convention into a repository instruction and check that Copilot applies it, in about ten minutes.
01
Pick one easy-to-violate convention in your repo, such as "API errors use the existing AppError class."
02
Create .github/copilot-instructions.md with project context, that observable rule, the test location, and your focused test command.
03
Ask Copilot to make a small related change, first listing the rules relevant to the task and the files it expects to change.
Hint: If it can't name the rule, the instruction didn't load on this surface. Don't assume it did.
04
If loading can't be confirmed, paste the instruction text above your prompt and rerun, and label that a manual test of the rule's quality, not proof it loaded.
05
Inspect any diff and run the focused command yourself.
A committed instruction file plus a before/after that shows whether the rule changed the plan, the diff, and the verification you ran.
Key takeaways
The Copilot CLI is a standalone terminal agent, distinct from gh copilot, and file edits need explicit approval.
Prove a prompt is deterministic: two identical runs, identical output, before scheduling or automating it.
Choose the narrowest customization layer that fully owns a behavior to avoid duplicated, drifting rules.
Put cross-repository baselines at organization scope, project rules in .github/copilot-instructions.md, one-off asks in the prompt.
Prompt files are reusable requests, custom agents are persistent specialists, and skills are complete procedures.
Check your understanding
1. You run the same CLI prompt twice on an unchanged repo and the two release reports differ. One even invents a missing date. What should you do before scheduling it or moving it into Actions?
2. How should you classify the rule "Never place credentials or customer data in prompts"?
3. A team needs a repeatable procedure that locates an HTTP route, inspects its schema, authorization, validation, tests, and examples, and marks anything unsupported as unverified. Which primitive fits best?
4. Which statement is true of the standalone Copilot CLI?
5. Which custom instruction is observable enough to check?
Frequently asked questions
Terms used in this lesson
Copilot CLI
The standalone terminal-native Copilot agent, launched with the copilot command and distinct from the older gh copilot extension.
custom instruction
Persistent background guidance that shapes repeated Copilot responses, such as a repository convention or a safety baseline.
prompt file
A reusable request template (a .prompt.md file) with explicit inputs and a required output contract.
custom agent
A named specialist defined in a .agent.md file, carrying a role, inspection policy, and guardrails that persist across a conversation.
agent skill
A reusable, multi-step procedure defined with a SKILL.md file, appropriate when a task needs a playbook rather than a single request.
