Custom subagents

Give a recurring job to a specialist helper instead of explaining it from scratch each time. You will create a project-specific website copy reviewer, limit it to reading files, and check that its advice points to real text on your site.

Before you start

• Claude Code installed and signed in, with a working session in your website project folder.
• A saved copy of the project and at least one page containing real headings, button labels, or service descriptions.
• An editor that can open hidden folders such as .claude. This walkthrough uses the terminal version of Claude Code.
• A short description of the people who use the site and the action you want them to take.

Want to do it yourself?

Difficulty

6 out of 10

Estimated completion time

45–90 minutes

Skills you’ll need: Define one reviewer role, inspect its available tools, and assess its suggestions before applying any changes.

I’ll do it myselfI’d rather get help

How this helps your brand

A dedicated copy reviewer can help check whether your website explains its service and next action clearly. Read-only tools and verified quotations keep the review separate from the decision to change your pages.

1. 1

   Step 1: Choose one job you can judge

   Start with a narrow task: find confusing wording on one page. For example, a visitor to a plumbing website should understand the service area and know which button requests an appointment.

   Write down the page and audience before creating the helper. A reviewer asked to improve everything has no clear stopping point. For this exercise, ask for at most three findings, each with the current wording, its file location, and a suggested replacement.

2. 2

   Step 2: Create a reviewer inside this project

   Paste the setup prompt below into Claude Code. It asks Claude to create .claude/agents/site-copy-reviewer.md. Project subagents live in .claude/agents/; a helper stored in your home folder under ~/.claude/agents/ is available across your projects instead.

   The file has a configuration section between two lines of three hyphens, followed by the reviewer instructions. Its name must be site-copy-reviewer, its description must explain the review job, and its tools must be Read, Glob, Grep. Set model to inherit so this example does not require choosing a particular model.

   Tip: If a helper with that name already exists, inspect it before changing it. Pick a different name if it belongs to another workflow.

3. 3

   Step 3: Inspect what the helper can do

   Open the new file yourself. Confirm that the tools list contains only Read, Glob, Grep. Leave out Bash, Write, Edit, and Agent for this exercise. The reviewer needs to find and read text, not run commands, change pages, or delegate the work again.

   Read the instructions beneath the configuration. They should tell the reviewer to quote existing wording, identify the file, suggest replacements, and say when it cannot find the requested page. Remove any instruction that asks it to rewrite files automatically.

   A subagent has its own conversation context. Put the audience, page, and review question in each assignment rather than assuming the helper knows everything you discussed earlier.

   Illustrated exampleSet the reviewer’s read-only boundary

   .claude/agents/site-copy-reviewer.md Read-only reviewer

   ✓ Can inspect

   • ReadOpen assigned page text
   • GlobFind matching files
   • GrepLocate wording in files

   access boundary

   × Cannot change

   • BashRun project commands
   • Write / EditModify website files
   • AgentDelegate another task

   The main conversation can apply a verified suggestion later.

4. 4

   Step 4: Ask for a review by name

   Start a fresh Claude Code session in the same project after creating the helper. This also handles the case where .claude/agents/ did not exist when the earlier session started.

   Send: Use the site-copy-reviewer subagent to review [page or file] for [audience]. The main action is [visitor action]. Return at most three findings and do not change files. Replace the brackets with your details.

   Check the transcript for a delegation showing site-copy-reviewer. Then open one cited file and find the quoted words. A useful finding might explain that “Continue” does not tell a visitor whether they are booking an appointment or asking for a quote.

   Illustrated exampleFollow a finding back to its source

   Claude Code transcriptdelegated

   you → site-copy-reviewer

   Review src/pages/services.tsx for local homeowners. Main action: request an appointment. Return up to three findings; do not change files.

   ↓

   site-copy-reviewer → finding 1

   “Continue” is unclear before booking. Check src/pages/services.tsx:18.

   Open the cited sourceservices.tsx

   17<form onSubmit={bookVisit}>

   18 <button>Continue</button>

   19</form>

   ✓

   Evidence matches. Now ask the main conversation to change this button label.

5. 5

   Step 5: Recover when the result is missing or vague

   If Claude cannot find the helper, check the folder, the .md extension, and the name and description fields. Restart from the project folder and invoke the exact name again. Current /agents guidance points to creating or editing these files; older versions may show a management wizard.

   If the reviewer cannot find a page, give it the source file path. If it invents wording or returns general advice, ask for the exact existing text and a file location for every finding. Discard findings you cannot confirm.

   Check your editor’s changed-file view after the review. Apart from the helper definition you deliberately added, the review exercise should leave the website files unchanged.

   Illustrated exampleRoute vague or missing results to a check

   ?

   What went wrong?Check the output before using a suggestion.

   No helper found↘

   Check setup

   Project folder · .claude/agents/ · .md · exact name

   Restart session, invoke by name

   Page missing or vague↘

   Ask for evidence

   Give the source path; require exact quote and file location.

   Discard anything you cannot confirm

   Files changed↘

   Inspect changed-file view

   Only the helper definition should be new.

   Keep the review read-only

6. 6

   Step 6: Apply one suggestion separately

   Choose one verified suggestion and ask the main Claude Code conversation to make that specific change. The reviewer itself stays read-only. Open the page in your usual preview and check the new wording in context, including a narrow phone-sized window.

   Reuse the same reviewer on a second page with a fresh assignment. If the output format drifts, improve the saved instructions and start another session before testing again.

Create a project subagent for reviewing website copy. First check whether .claude/agents/site-copy-reviewer.md already exists; if it does, show me what is there before replacing anything.

Create that Markdown file with YAML frontmatter containing name: site-copy-reviewer, a short description explaining when to use it for website wording reviews, tools: Read, Glob, Grep, and model: inherit.

Its instructions should make it read-only. Review only the page assigned in the delegation, for the audience and visitor action supplied there. Return at most three findings. For each, quote the existing wording, give the source file and line location, explain the visitor’s likely confusion, and suggest a replacement. Do not invent services, prices, claims, or contact details. If the page or evidence is missing, say what is missing. Do not run commands, edit files, or delegate.

Show me the finished definition and explain how to invoke it for [page or file], aimed at [audience], where the visitor should [main action]. Do not run the review yet.