in this chapter, we explore one of the most powerful features of GitHub Copilot in agent mode: custom instructions. While previous lessons have focused on editing and enhancing existing codebases, this chapter marks a shift—learning how to create new projects from scratch using instruction files.
Introduction to Custom Instructions
Custom instructions allow you to define exactly what you want Copilot to build, acting as a blueprint for your AI coding assistant. You can provide these instructions through a plain text file (instructions.txt) or a markdown file (instructions.md). These files contain natural language descriptions of the desired application, features, technologies, and constraints.
To illustrate, let’s consider a simple project: a to-do list web app. We create an instructions.md file describing what the app should do:
-
Users can add, view, and delete tasks.
-
Tasks are stored using the browser's localStorage.
-
The application should be responsive and user-friendly.
-
Technologies used: HTML, CSS, and JavaScript only—no backend, no external APIs.
This concise yet detailed instruction set serves as input for Copilot's agent. Upon processing, Copilot automatically generates the necessary files: index.html, styles.css, and script.js.
Executing the Instructions
After dragging the instructions file into the VS Code workspace and prompting Copilot to "implement the requested features," it creates the full app. The application runs instantly using VS Code’s "Go Live" feature. Tasks persist after refreshing the page, thanks to localStorage, demonstrating a fully working and responsive solution—all built within seconds.
Layering Instructions for Advanced Features
One exciting element of Copilot’s instruction handling is the ability to stack multiple layers of requirements. For example, an instructions_2.txt file can contain sequential tasks:
-
Write a
README.mdfile detailing the app’s functionality. -
Add inline documentation to all JavaScript functions for easy developer collaboration.
Copilot processes these in order, updating both the codebase and documentation seamlessly.
The .github Folder and Persistent Instructions
For more advanced workflows, developers can add a .github folder to their project and place a copilot-instructions.md file inside. This special file provides persistent context for Copilot across sessions. It’s ideal for setting coding standards, naming conventions, or technology requirements, ensuring consistency throughout the development process.
However, for beginners, adding a simple instructions.md or instructions.txt in the root folder is more than enough. Copilot reads and processes these on the fly, offering fast and tailored code generation.
Custom instructions elevate Copilot from an autocomplete tool to a collaborative partner that can interpret and act on your goals. Whether you want to build an app, document your project, or review your codebase, instructions empower you to shape the outcome with precision.