Creating Agents – Templates as Shortcut or Scaffolding from Scratch

In the previous posts of this series I wrote a lot about what agents do – which roles they take on, why the separation into planning and implementation agents makes sense, and how the Human-in-the-Loop checkpoint ensures quality. What I have only mentioned in passing so far: how these agents actually come into being. How you create them, adapt them to your own project – and which path is worth taking when.

That is the focus of this post.

Two Ways to Your Own Agent Team

There are two sensible ways to set up an agent in Claude Code or GitHub Copilot. Both work, both have their place – and both ultimately produce the same Markdown file.

Path A: Templates as a starting point. Copy a finished agent definition from a public repository into your own project and adapt it to your own codebase.

Path B: Scaffold from scratch. Use the built-in /agents command in Claude Code or the /create-agent skill in GitHub Copilot to generate an empty agent file from a role description – and then fine-tune it.

Which path is better depends on whether you have seen a similar role before. I use both – and combine them too.

Path A: Templates as a Shortcut

For the four roles I described in the previous posts – Business Analyst, Solution Architect, Implementation Plan Agent, and Developer Agent – I have published my own agent definitions as templates on GitHub. They are the direct write-up of what I use daily in my projects – including the path conventions, document structures, and explicit limits each agent must adhere to.

The advantage of this path is obvious: you get not only a role description, but also the structural decisions I described in the previous posts – the storage format for use cases, the step structure of the implementation plan with validation and cleanup, the explicit boundary of the Solution Architect not to write code.

The downside is equally obvious, and I don't want to gloss over it: A template is never a finished setup.

The paths in the templates point to docs/usecases/, docs/loesungskonzept/, and docs/plan/. That works if you are willing to adopt these conventions – or you adapt them. The validation commands in the implementation plan template are tailored to npm run build and flutter analyze. The referenced coding guidelines are mine. Anyone wanting to use the Solution Architect for a Java backend will need different layers in the action catalog table than for a Flutter frontend.

Templates therefore relieve you of the rough draft – they don't relieve you of the responsibility to sharpen them for your own project.

How I Proceed When Using a Template

My workflow is always the same:

1. Copy the template file into my .claude/agents/ directory – ideally under the name I want to use in the prompt (business-analyst.md, solution-architect.md, …).
2. Search through the paths in it and adapt them to my directory structure.
3. Bend the references to coding guidelines so they point to the file in my repo – not the GitHub variant.
4. Check the explicitly described handoffs: does the agent really expect as input the format that my upstream agent produces?
5. Only then deploy the agent for the first time on a small, isolated use case – and sharpen what shows up in practice.

That typically takes ten to twenty minutes per template. It is not zero effort, but it is significantly less than thinking through the same agent from scratch.

Path B: Scaffold from Scratch

When I need a role for which no template exists – such as a code reviewer with a security focus or a migration agent for a specific library – I take the second path. Both tools I use bring their own command for this.

Claude Code: /agents

Claude Code comes with a built-in way to create new agents: the /agents command. When you invoke it, Claude Code walks you through a guided process – it asks for the name, role, and behavior of the agent – and at the end creates a finished .md file in the .claude/agents/ directory of the project.

The result is a good first draft. But it is only a draft.

What /agents doesn't know: how my codebase is structured. Which conventions I use in my Vue components. That my agents should store their results in specific directories. That there is a Solution Architect whose solution design the Implementation Plan Agent expects as input. These connections don't exist in the freshly generated agent – they have to be incorporated afterwards.

For me this is not a disappointment but a clear division of labor: /agents handles the scaffolding. The project-specific fine-tuning is my job.

GitHub Copilot: /create-agent

GitHub Copilot has its own way of creating agents: the built-in /create-agent skill in Copilot Chat. You invoke it, describe the desired role, and Copilot creates an .agent.md file with the same basic structure as the Claude agents – role description, behavior, limits.

My experience: it works – but with a limitation I had to discover for myself.

The quality of the generated agent depends heavily on the model with which you invoke /create-agent. When Copilot gives you the choice, I would recommend deliberately switching to an OpenAI model. Not because the other models are fundamentally worse – but because Copilot has delivered more consistent results with OpenAI models in this specific use case. The agent definitions were more precise, the role descriptions clearer, the limits sharper.

This is a concrete adjustment that makes a difference – and that I have not found documented anywhere. Only through experimentation.

GitHub describes the concept in the official documentation under Creating custom agents via Markdown – a readable introduction that shows how roles are structured and behavior defined. What is missing there is the fine-tuning for a specific codebase. That is manual work, regardless of which tool you use.

The Trick for Copilot: Have Copilot Translate Templates

What happens when I want to use a Claude Code template for GitHub Copilot? The templates from the GitHub repository are tailored to Claude Code agents – frontmatter, tool references, and the way follow-up questions are formulated all follow Claude conventions. Copying them one-to-one into an .agent.md file works, but the result is not optimal.

Here is the trick I have gotten into the habit of using: Take the Claude template as a blueprint and ask GitHub Copilot to adapt it according to the best practices for Copilot.

The prompt looks roughly like this:

"Here is an agent template originally written for Claude Code. Please adapt it according to GitHub Copilot agent best practices. Keep the functional role, the path conventions, and the explicit limits – but translate structure, frontmatter, and tool references into what Copilot expects."

For this I deliberately switch Copilot to an older model – specifically GPT-5.5 or older. The newer models tend to interpret the task too creatively and rewrite the role contents. The older models stick more strictly to the directive "only adapt the format" – and that is exactly what I want at this point.

The result is a Copilot variant of the agent that is functionally identical to my Claude version, but speaks the tool idiom of the respective tool. I don't need to think through the role twice – I just need to have it brought into the right form once.

Three Things That Make Every Agent Truly Deployable

Whether I use a template as a starting point or scaffold with /agents or /create-agent – before an agent enters my workflow, I look at three things.

First, context. Does the agent know where it is? Does it know the directory structure, the documentation paths, the existing artifacts it should build on? A Business Analyst that doesn't know finished use cases should land under docs/usecases/ will store them somewhere – or invent its own convention.

Second, handoffs. Does the agent know who worked before it and who comes after? The Implementation Plan Agent does not receive a free-form concept – it receives the specific output format of the Solution Architect. This expectation must be explicitly described in the agent.

Third, limits. What should the agent explicitly not do? A Solution Architect that I don't explicitly forbid from writing code will eventually start trying. One line – "You do not write implementation code" – prevents this more reliably than any after-the-fact phrasing in the prompt.

That sounds like small stuff. In practice it is the difference between an agent that supports my workflow and one that invents its own. The templates from my repo have these three areas already filled in – but with my values. Anyone adopting them has to bend them to their own values.

When Invoking: Finding the Right Agent

One thing that often gave me results that didn't match my expectations early on: both tools have different mechanisms for activating the right agent – and both only work when you know how.

Claude Code: Name Explicitly

Claude Code does not always automatically select the right sub-agent – at least not reliably.

The solution is simple: I name the agent explicitly in the prompt. Instead of "Create a use case for the search function" I write "Use the Business Analyst and create a use case for the search function." Since I started doing this consistently, the right agent runs. Not sometimes – always.

That sounds like a small thing. But it is the difference between a workflow that works reliably and one where you're never quite sure which role the agent is currently taking on.

Anthropic describes the concept of sub-agents and the official introduction framework in their Introduction to Sub-agents: the idea is exactly this isolation – separate context windows, focused tasks, no mixing of roles. What is not stated there: that you need to actively point to this isolation in the prompt for it to actually take effect.

GitHub Copilot: Agent Picker in the Chat Window

With GitHub Copilot it is not enough to name the agent in the prompt – you have to actively select it in the chat window. At the top of the Copilot chat window there is a selector through which you can switch between available agents. Only when the right agent is selected there does Copilot work in its role.

This is a different interaction pattern from Claude Code. With Claude Code the prompt is the interface – the agent is activated through language. With Copilot it is the UI. Both have their logic: Claude Code is a CLI tool, Copilot is deeply integrated into VSCode. Each tool uses the channel that is natural in its environment.

Whoever forgets this and sends a prompt without agent selection works with the default Copilot – and wonders why the style, context, and output don't fit. This happened to me often enough before I got into the habit of first selecting the agent and then describing the task.

My Setup: Two Tools, One Workflow

Both tools work – but in different ways, with different emphases.

Claude Code relies on file-based agents in .claude/agents/, controlled through the prompt. The workflow is terminal-close: I type, the right agent responds, the result lands as a file in the project. Integration into my own project structure is frictionless because the files are directly in the repository and version-controlled. Anyone working on my project immediately has all agents at hand.

GitHub Copilot relies on UI integration: the agent picker is visual, the workflow runs in VSCode, the results appear directly in the context of the current file. For the moment of implementation, when I'm writing code and need immediate feedback, that feels more natural.

My practical setup is therefore not an either-or, but a division of labor. The planning phase – Business Analyst, Solution Architect, Implementation Plan – runs via Claude Code in the terminal. The Developer Agent, which works in the context of active files and the IDE, runs via Copilot. For each context the respective tool is the more natural channel – and that is reflected in the agents I create for each tool.

Anthropic describes this modular approach in their article Equipping agents with Agent Skills: specialized capabilities packaged into reusable files, instead of pressing everything into a single agent. The principle applies equally to the GitHub Copilot agent on the other side – and to the interplay of both.

Conclusion

Creating agents is not a one-time effort that then runs forever. It is an iterative process: choose a starting point – template or scaffold – adapt it to the project, observe in use, sharpen it.

Whoever wants to start quickly and needs one of the four roles from this series can find the templates on GitHub. Whoever wants to design their own role can also get to a basic structure quickly with /agents in Claude Code or /create-agent in Copilot. Whoever uses both tools can save themselves the back-and-forth by having a Claude template translated into a Copilot-compliant variant via Copilot with GPT-5.5 or older.

What none of these paths replaces is the part that comes after: adapting to your own codebase, the explicit handoffs between the agents, the clearly drawn limits. Exactly the part that makes the agent truly useful – and exactly the part no tool and no template can take off your hands. You have to bring it yourself. But it is manageable: ten to twenty minutes per template, half an hour for a scaffolded agent. An investment that pays off after the second or third deployment – because then the agent delivers what I expect without me having to explain it anew every time.