GitHub Copilot has quickly become a game-changer for developers, not just for writing code but also for automating repetitive tasks. In this post, I’ll dive into a powerful feature that helps you further tailor Copilot’s behavior to your specific needs: custom instructions. I’ll explain how creating a markdown file with instructions in your GitHub repository can guide Copilot to perform tasks just the way you want—whether it’s transforming SQL syntax or something else entirely.
The Power of Custom Instructions
Custom instructions allow you to control how GitHub Copilot generates code suggestions. Normally, Copilot provides suggestions based on its understanding of your code context, but sometimes you need more specific guidance. That’s where instructions come in. By creating a simple markdown file within your GitHub repository, you can specify exactly how Copilot should behave in certain situations. This is especially useful when you want Copilot to follow specific coding conventions, perform repetitive transformations, or even handle complex refactoring tasks.
In this post, I’ll share an example where I used custom instructions to transform CREATE TABLE SQL syntax into ALTER TABLE syntax. This allows me to update my database without dropping tables or losing data. But the real takeaway is that these instructions can be adapted to almost any scenario.
Setting Up Your Instructions File
To get started, you need to create a .github folder in your repository (if one doesn’t already exist). Inside that folder, create a markdown file (copilot-instructions.md) where you’ll write your instructions.
Here’s a quick example of the folder structure:
/your-project
├── .github/
└── copilot-instructions.md
In the copilot-instructions.md file, you’ll write specific instructions on how Copilot should behave. The key here is that these instructions will only be followed when you explicitly tell Copilot to use them. You can trigger Copilot to use these instructions with a command in your prompt, like: “USE INSTRUCTIONS FILE”.
Here’s a sample instructions file:
# Only use this section of instructions when the instruction "USE INSTRUCTIONS FILE" is given in the prompt ## Goal Convert MySQL exports with `CREATE TABLE` statements to `ALTER TABLE` syntax to avoid dropping existing tables and data. ## Steps ### 1. Identify `CREATE TABLE` Statements - Find each `CREATE TABLE [table_name]` block. - Extract the table name and column definitions. ### 2. Replace with `ALTER TABLE` - Change `CREATE TABLE [table_name]` to `ALTER TABLE [table_name]`. - Remove the brackets and table creation syntax. - Convert each column definition to: ```sql ADD COLUMN IF NOT EXISTS [column_name] [data_type] [constraints]; ``` - Include `NOT NULL` and `DEFAULT` values as needed. ### 3. Handle Keys and Indexes - Replace `PRIMARY KEY` with: ```sql ADD PRIMARY KEY IF NOT EXISTS ([column_name]); ``` **Note:** Check if the primary key already exists before adding it. - Use similar checks for `UNIQUE` keys. - Remove `AUTO_INCREMENT` properties—handle them separately. ### 4. Ignore Unnecessary Statements - Skip or delete `DROP TABLE`, `CREATE DATABASE`, or `USE [database_name]` lines. - Remove options like `ENGINE=`, `CHARSET=`, and `COLLATE=`. ## Example ### Input ```sql CREATE TABLE NewsItems ( news_id int(11) NOT NULL, news_title varchar(255) NOT NULL, news_category varchar(100) DEFAULT NULL, news_start_date varchar(100) DEFAULT NULL, news_end_date varchar(100) DEFAULT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci; ``` ### Output ```sql ALTER TABLE NewsItems ADD COLUMN IF NOT EXISTS news_id int(11) NOT NULL, ADD COLUMN IF NOT EXISTS news_title varchar(255) NOT NULL, ADD COLUMN IF NOT EXISTS news_category varchar(100) DEFAULT NULL, ADD COLUMN IF NOT EXISTS news_start_date varchar(100) DEFAULT NULL, ADD COLUMN IF NOT EXISTS news_end_date varchar(100) DEFAULT NULL; -- Check if the primary key is already set before adding it ALTER TABLE NewsItems ADD PRIMARY KEY IF NOT EXISTS (news_id); ``` ## Notes - Use `ADD COLUMN IF NOT EXISTS` to avoid errors. - Use `ADD PRIMARY KEY IF NOT EXISTS` to prevent multiple primary key errors. - Keep key alterations (`PRIMARY KEY`, `UNIQUE`) in separate `ALTER TABLE` commands. - Ensure compatibility with your MySQL/MariaDB version.
How to Use the Instructions File with GitHub Copilot
Once your instructions file is set up, it’s easy to trigger Copilot to follow the guidelines. In VS Code, simply prompt Copilot with something like: **”USE INSTRUCTIONS FILE”**. This tells Copilot to read the instructions from the .github/copilot-instructions.md file and apply them to your code. For example, let’s say you have a SQL file with `CREATE TABLE` statements and you want Copilot to automatically transform these into `ALTER TABLE` commands.- You have an SQL file with Create Table statements
- You open the file in VS Code and ask GitHub Copilot something like “Transform the create statements into alter statements **USE INSTRUCTIONS FILE**”
- Copilot reads the instructions and transforms t he SQL syntax according to your guidelines.
sql CREATE TABLE NewsItems ( news_id int(11) NOT NULL, news_title varchar(255) NOT NULL );Transformed output:
ALTER TABLE NewsItems ADD COLUMN IF NOT EXISTS news_id int(11) NOT NULL, ADD COLUMN IF NOT EXISTS news_title varchar(255) NOT NULL;With this approach, you save time by automating the transformation of repetitive code patterns, and you ensure consistency in how Copilot applies your instructions.
Why Use Instructions Files?
The beauty of the instructions file is its flexibility. It’s not limited to SQL transformations. You can use it to:
- Enforce consistent coding styles across your team.
- Automate common refactoring tasks, like renaming variables or changing function signatures.
- Integrate specific tools or libraries by providing detailed instructions on how Copilot should generate code.
For instance, you could use instructions to ensure Copilot uses specific design patterns, applies certain linting rules, or even structures comments in a particular way. The instructions file serves as a powerful customization tool to make Copilot work exactly how you want it to.
Conclusion
GitHub Copilot’s ability to follow custom instructions through a markdown file opens up a whole new world of automation and customization. Whether you’re transforming SQL syntax, enforcing team coding standards, or automating repetitive refactoring tasks, the instructions file feature is an incredibly powerful tool. The best part? You have full control over when and how Copilot applies these instructions, ensuring that it adapts to your workflow without overstepping.