In this post, I’ll show you how to build a simple editing agent in Visual Studio Code with GitHub Copilot. Then, I’ll use it to review a draft with suggested copy edits. An agent that quickly applies a style guide to a document and suggests edits for review can save you a lot of time, especially if your editing backlog suddenly increases. Running the agent in your IDE gives you inline edits and suggestions, while still letting you decide which changes to accept.

Prepare the Style Guide

Your organization may already have a style guide. If it’s in a PDF or on a website, convert it to plain text or Markdown before using it with your editing agent. Doing this makes the content easier for the agent to work with and can reduce AI credit usage. You can use an LLM to help with the conversion.

If your organization uses the Microsoft or Google style guides, both are available in Markdown on GitHub. You can download the source files here:

• Microsoft Writing Style Guide
• Google Developer Documentation Style Guide

Create the Editing Agent

Next, create a reusable editing agent that applies your chosen style guide to a file and suggests edits for review.

I created a simple agent and saved it as style.agent.md in the .github/agents/ folder of my repository. The file uses plain-language instructions, plus optional YAML front matter for metadata such as the agent name and description. Once you add it to your repository, it appears in the agents menu at the bottom of the GitHub Copilot chat window.

style.agent.md

---
name: style-guide-agent
description: Applies the Google style guide.
tools: [read, agent, edit, search, web]
---

Apply the following Google style guide rules to any file or lines of text that I specify. Read the rules each time before suggesting edits, in case they have changed. 

Suggest edits for grammar, clarity, and consistency with the style guide.

I would like to review and accept or reject each suggested change.

Suggest final text only. Do not use strikethrough, tracked-change markup, or inline suggestion formats (such as ~~deleted~~ added). Apply changes directly in the file unless I explicitly ask for review mode.

# Google Style Guide Rules

(The pasted content of the Google style guide in Markdown format, which is available at the following URL: 

https://github.com/google/styleguide/blob/gh-pages/docguide/style.md)

Note: Downloading the Google style guide in Markdown format and copying it into your agent file will save you time and AI credits.

Test the Editing Agent

Then, choose a sample passage that needs work. I asked GitHub Copilot to generate one with common clarity and grammar issues, and I copied it into a new file named bad-paragraph.md. The original paragraph read:

To install the telemetry service you just run the setup thing and it should mostly work unless your computer is old or new in a weird way, then maybe do the manual process from the docs somewhere. The API key goes in the config but also maybe in env because both methods are supported except when one is ignored by the runtime for security reasons, which is normal. After deploy, check logs for ERR42 because it means either timeout, auth, DNS, memory pressure, or other networking, so if you see that then retry 2-3 times and clear cache and restart all pods even in single node mode. The dashboard latency number can be trusted except when sampling drops packets, so if it says green but users complain then increase buffer from 64 to 4096 and disable strict mode temporary, then circle back and harden later once traffic stabilizes.

Finally, I opened bad-paragraph.md in Visual Studio Code, selected the style-guide-agent in the GitHub Copilot chat panel, and prompted it to apply the style guide to the file.

The revised paragraphs read:

To install the telemetry service, run the setup script. If the default installer fails because of system incompatibility, follow the manual installation instructions in the documentation. Store the API key in either the configuration file or environment variables, and use one method consistently per environment.

After deployment, check logs for ERR42. This error can indicate timeout, authentication, DNS, memory pressure, or network issues. If it appears, retry two or three times, clear the cache, and restart all pods, including single-node deployments.

Use dashboard latency as a useful signal, but validate it against user reports because sampling can drop packets. If the dashboard looks healthy while users still report slowness, increase the buffer from 64 to 4096, temporarily disable strict mode, and re-enable hardening after traffic stabilizes.

Running the agent took only seconds, and the improvement in clarity and coherence was noticeable right away. Of course, technical writers can still find more ways to improve this text, but the agent’s instructions are to copy-edit the text and apply style rules. You can add more instructions to include formatting rules, such as making bulleted or numbered lists where needed and adding headings.

Conclusion

Setting this up took less than ten minutes, but the real value shows up when you use the agent on real drafts. Start with one document, review each suggestion, and accept only the changes that match your voice and intent. As you do this, you’ll quickly see which rules are worth keeping and which ones need to be adjusted. After a few rounds, you can refine the agent into a dependable part of your editing workflow. Thanks for reading, and I’d love to hear how it works for you.

Instead of treating AI as a separate application, you can make it part of your documentation workflow. This post is intended for technical writers who use Git to manage HTML, DITA, or Markdown documentation, especially those working in Visual Studio Code (VS Code) as their integrated development environment (IDE). These concepts may also apply to other IDEs.

AI assistants such as Claude Code, GitHub Copilot, and OpenAI Codex integrate directly into VS Code and other IDEs, allowing you to work alongside AI without leaving your editor. You can use these tools to build shared automations that improve documentation quality, consistency, and efficiency. GitHub Copilot integrates most naturally with VS Code’s built-in capabilities, but the other AI assistants are also worth exploring within VS Code.

Documentation engineering

The role of the technical writer is shifting. We are no longer just creating documentation; we are building solutions that generate content automatically. Technical writers are increasingly combining traditional writing skills with lightweight automation, prompt design, scripting, and AI workflows to improve content quality and consistency.

If you’re not using AI assistants, you’re missing an opportunity. The good news is that you can get up to speed quickly. You do not need to become a software engineer to benefit from them. A basic understanding of Visual Studio Code and AI assistant extensions can improve your productivity by helping you automate repetitive tasks, focus on broader content strategy, and add your own voice to the content.

Configure Visual Studio Code for AI

To get started, install one or more AI assistant extensions in Visual Studio Code. Your company may already have a preferred AI vendor, but if not, GitHub Copilot may be the easiest place to start because it integrates seamlessly with Visual Studio Code. You can also experiment with the Claude Code or OpenAI Codex extensions within VS Code.

GitHub Copilot is available as a free extension from the Visual Studio Code Marketplace. If your GitHub account includes free or paid Copilot access, you can start experimenting immediately. After installing the extension, open the chat panel by selecting the speech bubble icon at the top of the Visual Studio Code window. GitHub Copilot allows you to choose your large language model (LLM). The paid plan gives you access to more models.

If you have a Claude or OpenAI account, even on the free tier, you can install the corresponding Visual Studio Code extensions at no additional cost. After installation, sign in with your account. You can then open the AI assistant panel by selecting the Claude Code or Codex icon in the upper-right corner of the Visual Studio Code window.

Regardless of which AI assistant you choose, it appears as a sidebar alongside your editor, allowing you to interact with it while working on your documentation. You can enter prompts, ask for suggestions, allow the AI assistant to edit files directly, and accept or reject edits without leaving Visual Studio Code. Each AI assistant provides options near the chat box that control whether it can edit files directly, as follows:

• In GitHub Copilot Chat, the Agents menu lets you choose between Agent, Ask, or Plan modes. Agent mode gives GitHub Copilot permission to edit your files directly. A separate permissions menu lets you choose whether to approve each attempt to run scripts or bypass approvals.
• In Claude Code, the Modes menu below the chat box includes options ranging from Manual to Auto. Each option is described in the menu itself.
• In Codex, the Approvals menu below the chat box includes options ranging from Ask for approval to Full access.

After you configure how your AI assistant can interact with your files, the next step is to teach it how your documentation should be written. You can do this by giving the assistant access to your style guide and creating reusable workflows that improve quality, consistency, and efficiency.

See the next post in this series, editing with AI in Visual Studio Code, for more information on how to give your AI assistant instructions and reusable workflows.

Every documentation team has a style guide. Whether it’s based on the Microsoft Writing Style Guide, the Google Developer Documentation Style Guide, or an internal company standard, writers have traditionally spent a significant amount of time checking capitalization, terminology, sentence structure, formatting, and consistency.

Now that you have configured your AI assistant within your IDE, you can use persistent instructions to apply style rules automatically. These instructions can be stored in one of the following ways:

• Context files, which you can attach to the chat window for one-time use.
• Shared prompts, which you can store in a repository folder for repeated use.
• Instruction files, which you can store in a repository folder and reference from prompts.

The following sections explain each approach and how it can improve your documentation workflow. They are presented in order of increasing complexity, but you can start with whichever approach best fits your team’s needs.

Context files

Context files are the simplest option. These are files that you share with your AI assistant by uploading them or dragging them into the chat window. For technical writing, your style guide is an excellent candidate for a context file. Ideally, it should be written in Markdown or plain text so that an LLM can process it easily. LLMs can help you convert your style guide from its current format into Markdown or plain text if needed.

After attaching the context file or dragging it into the chat window, you can enter a simple prompt such as:

Edit the file that is currently open, index.html, using the style rules in the attached context file, style-guide.md. Suggest edits for me to accept or reject.

The results can be surprisingly effective. You remain in control by reviewing and accepting or rejecting each suggested change, while the AI assistant helps your team apply style guidelines consistently regardless of individual writing experience.

Copilot in VS Code stands out over Claude and Codex

GitHub Copilot, Claude Code, and OpenAI Codex all support context files in Visual Studio Code, but GitHub Copilot stands out because it integrates well with VS Code’s built-in capabilities. You can drag a context file into the chat window and then use Agent mode to allow GitHub Copilot to edit files directly. GitHub Copilot lets you keep or reject each change inline through a drop-down menu in the editor. You can choose to keep or reject all changes in a file from the drop-down menu at the bottom of the file, or all changes in multiple files from the GitHub Copilot chat panel.

Reviewing updates from GitHub Copilot is more user-friendly in VS Code than using Claude or Codex. For writing teams that want to keep a human in the loop (HITL), this is an easier option. And if you prefer Claude or Codex as your LLM, GitHub Copilot lets you select the model you want to use, including Claude or Codex.

Shared prompts

Instead of recreating prompts from scratch each time, or copying and pasting them from a shared file or wiki page, you can store prompts in a shared folder in your repository so that everyone on your team has access to commonly used prompts. This approach works especially well for longer or more complex prompts that writers use repeatedly.

Each AI assistant uses a slightly different repository structure for storing shared prompts. Regardless of the implementation, the goal is the same: make prompts easy for the team to find and reuse. Most AI assistants expect prompt files to be written in plain text or Markdown.

• GitHub Copilot defines a standard location for shared prompts. You can create a prompt file in the .github/prompts/ folder of a repository and name the prompt file with the -prompt.md suffix. For more information, see Prompt files in the Visual Studio Code documentation.

• Claude Code uses a different approach. Shared prompts are typically stored in the .claude/commands folder within the repository. Writers can invoke these commands by typing a / in the chat window and then selecting the appropriate command.

• OpenAI Codex doesn’t define a standard location for shared prompts. Instead, your team can agree on a repository folder for storing prompt files, which writers can then copy and paste into the chat window as needed.

Instruction files

Instruction files, sometimes called rule files, contain guidance that you want your AI assistant or custom agent to follow. A style guide is a good candidate for an instruction file, but instruction files can also contain other types of rules and guidelines. If you store your style guide as an instruction file in your repository, you won’t need to drag it into the chat window as a context file because it will always be available for reference.

Like shared prompts, each AI assistant uses a different folder structure for storing instruction files in a repository.

• GitHub Copilot typically looks for instruction files in the .github/instructions/ folder of a repository. Instruction file names conventionally end with the .instructions.md suffix. For example, you might create a file named style-guide.instructions.md. GitHub allows you to apply instructions to a set of files in your repository when you submit a pull request. To do this, include front matter in the instruction file that specifies the files to which the instructions apply. For example, you might include the following front matter in your style guide instruction file:

---
applyTo: "/docs/*.md"
---

This applies the instructions in the style guide to all Markdown files in the docs folder of the repository. For more information, see Use custom instructions in VS Code in the Visual Studio Code documentation.

• Claude Code stores instruction or rule files in the .claude/rules/ folder of a repository. Rule files are Markdown files and can use descriptive names such as style-guide.md. You can reference the rule file directly by @-mentioning it in the chat window, such as @style-guide. For more information, see Organize rules with .claude/rules in the Claude Code documentation.

• OpenAI Codex supports skills, which package reusable workflows, instructions, references, and optional scripts. Codex stores repository-specific skills in .agents/skills/. Each skill is defined in its own folder and includes a required SKILL.md file that describes when to use the skill and how to perform the task. For example, a copy-editing skill folder might look like this:

.agents/
└── skills/
    └── copy-edit/
        ├── SKILL.md
        └── references/
            └── style-guide.md

The SKILL.md file might begin with the following front matter:

---
name: copy-edit
description: Copy-edit prose for grammar, clarity, consistency, and compliance with the repository style guide.
---

You can invoke the skill by typing $ followed by the skill name, for example $copy-edit, in the chat window. For more information, see Build skills and Skills in the OpenAI documentation.

I highly recommend that you try editing with AI in Visual Studio Code using context files, shared prompts, and instruction files. These techniques can help your team apply style rules consistently and efficiently across your documentation set. In the next post in this series Creating Custom Agents in Visual Studio Code, I’ll explain how to combine these techniques into reusable agents that automate entire documentation workflows.

Rather than issuing individual prompts, you can create reusable AI agents that perform multiple tasks. For example, when a project manager provides a draft topic, you can create an agent that:

1. Converts the draft into Markdown, HTML, or your repository’s preferred format.
2. Applies your team’s documentation template.
3. Retrieves supplemental information and links from internal or public knowledge bases.
4. Applies your documentation style guide before presenting the results for review.

You do not need to know a programming language to build an agent like this. By combining prompts, instruction files, and context files, you can create an agent that performs an entire documentation workflow. Think of it as giving the agent the same written instructions you would provide to a new technical writer on your team. The agent handles the repetitive work while you review the results and make the final decisions.

You can also create agents that perform specialized documentation tasks. For example, an API documentation agent might edit parameter descriptions to match your preferred writing style, clean up example values, and ensure consistent terminology across hundreds of YAML or Markdown files.

As with the prompts and instruction files mentioned in the previous post Editing with AI in VS Code, each AI assistant uses a different approach to define and store reusable agents.

• GitHub Copilot stores reusable agents in the .github/agents/ folder of the repository. Each agent is defined in a Markdown file that contains natural-language instructions describing the agent’s behavior and capabilities. Agent file names should include the .agent.md suffix. In the file, you can include YAML front matter to define metadata such as the agent’s name and description. After you add an agent to your repository, it becomes available from the Agents menu at the bottom of the chat window. For more information, see Custom agents in VS Code in the Visual Studio Code documentation.

• Claude Code stores subagents in the .claude/agents/ folder at the root of the repository. Each subagent is defined in a Markdown file with YAML front matter that describes the subagent’s responsibilities and includes the subagent’s instructions. For example:

---
name: copy-editor
description: Applies the style guide to the current file and suggests edits for review.
tools: Read, Grep, Write
model: sonnet
---
(Instructions for the copy-editor subagent go here.)

You can invoke the subagent by typing @copy-editor in the chat window or by asking Claude to use the copy-editor subagent. For more information, see Create custom subagents in the Claude Code documentation.

• OpenAI Codex stores project-specific subagents in the .codex/agents/ folder at the root of the repository. Each subagent is defined in a .toml file containing metadata such as the subagent’s name, description, and model, followed by natural-language instructions for the agent. You can invoke a subagent by asking Codex to delegate a task. For example, delegate article.md to the copy-editor agent. For more information, see Subagents in the OpenAI documentation.

Although each AI assistant organizes agents differently, they all follow the same principle: combining reusable instructions, tools, and context into specialized assistants that automate common documentation tasks.

Recap

If you want to add AI automation to your docs repository, the quickest way to compare the options is to look at where each assistant expects its files to live and what those files are named.

What’s Next?

Try experimenting with these techniques in Visual Studio Code or your preferred IDE. Explore different AI assistants to determine which works best for your team’s workflow. Start with simple context files, then gradually introduce shared prompts, instruction files, and custom agents as you build confidence.

As AI becomes a standard part of the documentation process, technical writers have an opportunity to contribute far beyond writing individual topics. We can build reusable workflows that improve quality, consistency, and efficiency across an entire documentation set. In doing so, we become documentation engineers who help shape how documentation is created.