Agents — Claude Code subagent system¶

Claude Code supports specialized subagents — Markdown files with YAML frontmatter that declare a name, model, tool list, and system prompt. When Claude Code spawns an agent, the harness loads the matching file and runs it with those settings.

The canonical agent roster for all HCS repos is documented in E:\git\demo-repository\AGENTS-PLAN.md. This file explains the format, conventions, and strategy. The roster is the source of truth for which repos have agents and which model each uses.

Agent definition format¶

---
name: agent-name
description: One-line description. Used by the harness to match spawn requests. Be specific.
model: haiku|sonnet|opus
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - WebFetch
  - WebSearch
  - mcp__claude_ai_Microsoft_Learn__microsoft_docs_search
  - mcp__claude_ai_Microsoft_Learn__microsoft_docs_fetch
  - mcp__claude_ai_Microsoft_Learn__microsoft_code_sample_search
---

Plain-text system prompt for this agent.
Tell it what it is, what it knows, what its constraints are.
Do not use YAML or JSON in the system prompt — plain prose only.

Rules: - name must match the filename (minus .md) exactly - description is shown in the agent list and matched when spawning — write it to be unambiguous at a glance - Only list tools the agent actually needs — narrower is safer - The system prompt body has no length limit but shorter is faster and cheaper - No secrets, credentials, or hardcoded values in any agent file

Two scopes¶

User-level (`~/.claude/agents/`)¶

Available in every repo session on this machine. Used for: - Domain expertise that spans many repos (e.g., Azure Local research) - Utilities that are repo-agnostic (e.g., Markdown editor, log triage) - Agents that serve multiple related repos where a separate agent per repo would be wasteful

Repo-level (`<repo>/.claude/agents/`)¶

Only available inside that specific repo. Used for: - Deep project-specific knowledge (module structure, cmdlet naming, test patterns, PSGallery publish flow) - Hard constraints that are unique to that repo (e.g., NEVER touch versioned_docs/, GUID folder requirement) - Anything that would be misleading or wrong if applied outside that repo

Model assignment strategy¶

Tier	Model alias	When to assign	Cost vs opus
Cheap	`haiku`	Read-only: "what does this file say", log triage, cheap one-shots	~20%
Default	`sonnet`	Most agents — code, writing, research, planning	~60%
Heavy	`opus`	Only for the deep cross-repo researcher (`azurelocal-domain-expert`)	100%

The rule is: default to sonnet. Opus is 5× more expensive per output token. The azurelocal-domain-expert is the only opus agent in the HCS roster because it genuinely needs deep synthesis across many sources simultaneously.

Current user-level agents¶

Agent file	Model	Tools	Purpose
`triage-lookup.md`	haiku	Read, Grep, Glob	Fast read-only: "what does this file say", find references, summarize logs. No writing.
`markdown-prose-editor.md`	sonnet	Read, Write, Edit, Glob	General Markdown/MDX editing — runbooks, READMEs, ADRs, blog drafts. Stack-agnostic.
`azurelocal-domain-expert.md`	opus	Read, Grep, Glob, WebFetch, WebSearch, Microsoft Learn MCP tools	Deep cross-repo research on Azure Local, Hyper-V, S2D, Network ATC. Only opus agent.
`mkdocs-material-doctor.md`	sonnet	Read, Write, Edit, Glob, WebFetch	MkDocs Material theme, plugins, nav config, mike versioning. Covers 14 repos.
`turner-module-scaffold-engineer.md`	sonnet	Read, Write, Edit, Glob, Grep	Turner Legacy scaffold modules (board, budget, calendar, finance, travel). All share the same Vite/React/TypeScript stub pattern.
`mms-2026-demo-presenter.md`	sonnet	Read, Write, Edit, Glob	MMS 2026 session demos (AVD demo, Hybrid Update Blues).

Archived agents (replaced 2026-04-30): azure-local-researcher.md, docs-writer.md, quick-lookup.md — in _archive_2026-04-30/.

Current repo-level agents¶

All repo-level agents use sonnet except demo-scratchpad-curator (haiku). See AGENTS-PLAN.md for the full table including which repos are pending and which are explicitly skipped.

Repo	Agent name
`azurelocal.github.io`	`docusaurus-doctor-azurelocal`
`azure-scout`	`azure-scout-engineer`
`azurelocal-ranger`	`ranger-engineer`
`azurelocal-s2d-cartographer`	`cartographer-engineer`
`azurelocal-vm-hydration`	`vm-hydration-engineer`
`azurelocal-toolkit`	`azl-toolkit-engineer`
`azurelocal-azloflows`	`azloflows-engineer`
`azurelocal-surveyor`	`surveyor-engineer`
`azurelocal-platform`	`platform-standards-keeper`
`demo-repository`	`demo-scratchpad-curator` (haiku)

Project 42 repos (project42.github.io, project42dev.github.io, project42dev/project42.github.io, thisismydemo/project-x) ship a 9-agent set as part of the framework — do not modify them.

Adding a new agent¶

Decide the scope: user-level (serves multiple repos) or repo-level (project-specific)
Pick the model: haiku for cheap reads, sonnet for everything else, opus only if genuinely needed
Copy templates/claude/agent.md.template to the appropriate location
Fill in all fields — name, description, model, tools, system prompt
Update AGENTS-PLAN.md in E:\git\demo-repository with the new entry
If repo-level, add the "Subagents available" stanza to the repo's CLAUDE.md
Commit: feat(claude): add <agent-name> agent

Retiring an agent¶

Do not delete agent files — move them to an _archive_<date>/ folder in the same directory. This preserves the audit trail and makes it possible to restore if needed.

Update AGENTS-PLAN.md to show the agent as archived.