Sue Jacobs

Building AI generated content solutions.   

10 minute read

For some technical writers, using AI means opening a standalone chat window, copying content into it, asking for suggestions, and then copying the results back into their documentation source files. While that workflow is useful, it barely scratches the surface of what’s possible.

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 apply to other IDEs as well.

AI assistants such as Claude Code, GitHub Copilot, and OpenAI Codex integrate directly into Visual Studio Code, 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. I have found that GitHub Copilot integrates best with Visual Studio Code, but the other tools are also worth exploring.

Documentation engineering

The role of the technical writer is shifting. We’re no longer just creating documentation; we’re building solutions that auto-generate content. 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 these tools, you’re missing an opportunity. The good news is that you can get up to speed quickly. You don’t need to become a software engineer to benefit from them. A basic understanding of Visual Studio Code and AI extensions can improve your productivity by helping you automate repetitive tasks, focus on broader content strategy, and add your own flair 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 to start with because it integrates seamlessly into Visual Studio Code. You can also experiment with Claude Code or OpenAI Codex, which are free for basic use.

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 window by selecting the speech bubble icon at the top of the Visual Studio Code window.

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 ChatGPT 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, and accept or reject edits without leaving Visual Studio Code. Each AI assistant also 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 from 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.

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:

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

Technique Best for
Context files One-time tasks using reference material
Shared prompts Reusing common prompts across a team
Instruction files Applying repository-wide rules and style guides
Custom agents Automating complete documentation workflows

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.

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

Edit the file that’s 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.

Shared prompts

Another option is to 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 it 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. These files can range from style guide rules to repository structure details, such as how to find API schema files. 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. You can use the instruction file directly by dragging it into the chat window as a context file, or you can create a custom agent that references the instruction file to perform a specific task. 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, or create a custom agent that uses the rule file when performing a task. For more information, see Organize rules with .claude/rules in the Claude Code documentation.

  • OpenAI Codex has a couple of equivalents to instruction files. Codex uses a repository-level AGENTS.md file which defines instructions for all Codex agents working in the repository. You can also reference supplemental files, such as a style guide in docs/style-guide.md, from AGENTS.md. For example, your AGENTS.md might include an instruction such as All agents that perform copy-editing tasks should follow the style rules in docs/style-guide.md.

Codex also 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 frontmatter:

---
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.

Custom agent files

The next step is where documentation engineering really begins.

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 don’t 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 prompts and instruction files, 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 frontmatter 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 frontmatter that describes the subagent’s responsibilities followed by 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 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 by combining reusable instructions, tools, and context into specialized assistants that automate common documentation tasks.

What’s Next?

Try experimenting with these techniques in Visual Studio Code or your preferred IDE. Explore different AI assistants to determine which best fits 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’re becoming documentation engineers who help shape how documentation is created.

Thank you for reading. In future posts, I’ll explore using other IDEs with AI assistants for technical writing, starting with Cursor. As AI assistant integrations in VS Code continue to improve, I’ll update this post as needed.

You May Also Enjoy