3 - Creating Custom Agents in Visual Studio Code

In my previous posts, we discussed how to get started with AI in Visual Studio Code and edit with AI in VS Code. The next step, custom agent files, 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 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.

Automation type	GitHub Copilot	Claude Code	OpenAI Codex
Shared prompts	Store prompt files in .github/prompts/ and name the file with the -prompt.md suffix.	Store command files in .claude/commands/ and invoke them with /command-file-name.	Use any repo folder such as prompts/ or similar, then paste or reference the prompt manually.
Instruction files	Put default repo rules in .github/instructions/ and name the file with the .instructions.md suffix.	Put reusable rules in .claude/rules/ as Markdown files such as style-guide.md.	Use the repo-level AGENTS.md for top-level instructions and optional .agents/skills/<skill>/SKILL.md files for reusable workflows.
Custom agents / subagents	Create agent definitions in .github/agents/ and name the file with the .agent.md suffix.	Create subagents in .claude/agents/ as Markdown files with YAML front matter, for example copy-editor.md.	Store project subagents in .codex/agents/ as TOML files such as copy-editor.toml.

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.

---