2 - Editing with AI in Visual Studio Code

Give AI instructions once

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.