Build what's next on GitHub, the place for anyone from anywhere to build anything.
Join us October 28-29 in San Francisco or online for GitHub Universe, our flagship developer event uniting people, agents, and the world's code.
Explore how you can set Copilot coding agent up for success with custom instruction and Copilot setup steps.
Modern development often starts with good intentions: a quick script, a prototype, maybe an action to automate one small thing. But as projects evolve, those early efforts can become brittle. What if you could bring clarity and structure to those projects without slowing down your momentum?
This tutorial shows how we used GitHub Copilot coding agent to refactor and enhance a personal GitHub Actions project called validate-file-exists. What started as a patchwork utility became well-structured, test-covered, documented, and set up for success with Copilot agent mode and coding agent.
We’ll walk through my example of:
copilot-setup-steps.yaml file to give the coding agent the needed tools in its environment.Back in November 2024, I created a small GitHub Action called validate-file-exists. I wanted to ensure certain files (like a dependabot.yml file, or .github/[copilot-instructions.md](http://copilot-instructions.md)) were present in a repository. If not, then the GitHub Actions workflow would fail. It supported comma-separated inputs and was meant to be part of a larger “baseline” of quality gates I use across projects.
It was functional, but I could have improved it further. It was missing docs, had inconsistent metadata, some gaps in input validation, and didn’t have Copilot custom instructions or Copilot setup steps to help set Copilot up for success. Time to fix that—with help from Copilot agent mode in VS Code.
Before bringing in the agent, I reviewed the existing copilot-instructions.md. It was sparse, without any description of the repository’s purpose, usage, or structure, nor any clear guidance for Copilot.
I based the instructions on best practices for using Copilot to work on tasks, by providing the sample custom instructions file in my prompt, and asking Copilot to update based on the codebase. In other words, I wanted it to provide:
Copilot had the right context on my expectations to guide it toward meaningful contributions. You can find the latest version here, but here’s a snapshot below:
Like any of us developers, Copilot coding agent needs a proper environment to work. That means setting up any required frameworks, installing dependencies, and making sure Copilot has access to the right tools to get the job done.
I created .github/copilot-setup-steps.yaml using the GitHub docs on customizing the development environment for Copilot coding agent. The example checks out the code, sets up Node.js, and installs the needed dependencies. Given this is a TypeScript action, that’s pretty much all I needed!
I made one minor change to the workflow: changing the node-version to be sourced from the .node-version file, to be consistent with my CI workflow:
Copilot coding agent has the needed dependencies and tools to build, lint, and test the codebase. As it makes changes to the codebase, it will be able to check for quality (as requested in our custom instructions) using the tools that were installed in the copilot-setup-steps.yml.
With the setup steps and custom instructions in place, it was time to find a task. So of course, I turned to Copilot. Using Copilot Chat in VS Code, we asked Copilot:
“What technical debt exists in this project? Please give me a prioritized list of areas we need to focus on. I would like to create a GitHub Issue with the top 2 or 3 items. Please include a brief problem statement, a set of acceptance criteria, and pointers on what files need to be added/updated.”
Within minutes, it explored the codebase and came back with a list of suggestions:
Notice how we asked for a problem statement, acceptance criteria, and guidance on the files to add/update? These come from the best practices for using Copilot to work on tasks. In other words, make sure your issues are well-scoped!
I asked Copilot to write an issue that addresses those three items. Once I created the issue, I assigned it to Copilot.
Once assigned, the agent kicked off a new pull request. Here’s what it did, asynchronously:
package.json name, description, URLs, and author field.As I delegated the task to Copilot, it freed me up to explain to the audience what it was doing, and how the Copilot setup steps and instructions work in the context of the agent’s session.
Copilot completed all tasks in just over 11 minutes. After a review of the agent’s approach, I approved the CI workflow so that it could run the standard quality checks on the codebase. The workflow failed, but through no fault of Copilot. I had some additional Markdown linting checks in the CI that weren’t in the instructions.
While I could have fixed it manually, it was a good opportunity to show how we can iterate on changes with Copilot. I added a new comment to the pull request, and asked Copilot:
“Our GitHub Action had a linting error for the markdown, can you fix that please?” (Also pasting the error from the GitHub Actions workflow.)
A few minutes later, it updated the code, pushed a new commit, and the pull request passed. And while Copilot was working on my task in the background, I was able to wrap up the stream.
While Copilot worked on the initial code changes for the GitHub Action, I showed off a second project: a Trend Radar visualisation app (here’s the repository) that I built using Next.js and Tailwind CSS.
Users had to manually input point data into forms. I wanted to:
I filed a GitHub issue describing the UX, acceptance criteria, and references.
After a few iterations of comments by working through the pull request, Copilot coding agent:
Playwright is now installed by default with the Copilot coding agent, which lets Copilot validate visual behaviors too.
This wasn’t just a cleanup session. It was a lesson in modern software collaboration. Copilot coding agent is our new teammate.
By structuring our repositories with context and intent, we invite Copilot to contribute meaningfully.
If you haven’t tried Copilot coding agent yet, think through your existing projects:
You might be surprised how much progress you can make in an afternoon.
copilot-instructions.md to steer the agent.copilot-setup-steps.yaml to give the agent the tools it needs.Ready to explore more? See how the GitHub billing team uses the coding agent to continuously burn down technical debt >