Agent vs PromptTemplate vs Skill

[safisa]

Discussion

Hi,

I already have some agents in my Theia app, each with its own registered tools. In our setup, we use the Orchestrator as the default agent, so if the user does not specify which agent to use, the Orchestrator agent can select the best agent for the user's prompt.

Since Theia now has several ways to provide a custom system prompt to the agent (prompttemplate file or skill file), this sometimes leads to confusion about which to use.

My questions are:

1. What is the best practice for using these custom prompts?
   (assume that there is no need to give each agent/prompt a different model; they can all use the same model)
   a. As I have now: specific agents with their tools.
   b. One master agent, with all other agents moved to skills that the master agent knows about and can choose from (in this case, the tools can be defined in each skill where needed).
   c. Same as b, but using prompttemplate files instead of skills.

2. What is the difference between prompttemplate and skill in Theia?
   (In both, we can set available variables and tools)
   a. What are the capabilities of each?
   b. When to use each?

Thanks

[github-actions[bot]]

Hi @safisa, thanks for starting this discussion! 👋

The Theia community will take a look soon. In the meantime, you might find helpful information in:

• 📖 Theia Documentation
• ❓ FAQ
• 💬 Previous Discussions

---

💙 Eclipse Theia is built and maintained by a community of contributors and sponsors. If Theia is valuable to your work, consider sponsoring the project. For professional support, training, or consulting services, learn more about available options.

[JonasHelming]

Hi,

Great questions and honestly, this is an area where things are moving incredibly fast and there's no single "right answer." Let me try to shed some light on the different mechanisms.

Prompt Templates vs. Skills

The difference is more technical/historical than conceptual. We've had prompt templates (.prompttemplate files) in Theia AI for about 1.5 years now. Skills (SKILL.md) were released more recently as an emerging standard across AI coding tools. We support skills specifically to allow users to leverage existing skills from that ecosystem. One notable difference though: agents are capable of loading skills on demand, which helps keep the context window lean until a skill is actually needed.

The Full Picture Is Even More Complex

In terms of what you can actually do to structure your AI setup, there are several mechanisms and they can be combined:

a) Orchestrator routing: The Orchestrator agent analyzes the user's request and routes it to the best-fitting agent. Importantly, the Orchestrator delegates the full session to the selected agent — once routed, the user stays with that agent for the remainder of the conversation. In our experience, results with this approach have been mixed. It tends to hide the existence of different agents from the user, which becomes problematic especially when agent capabilities are closely related to each other.

b) Agent-to-agent delegation: In contrast to the Orchestrator, this only delegates a single step to a sub-agent for a specific aspect, not the whole session. The key advantage is that everything happening in the delegation does not pollute the context of the main session — it's a clean delegation with defined input and output, and the sub-agent can have its own separate set of tools. Example: a GitHub agent can handle a GitHub-related action (collect info, create a PR, etc.) and return only the result to the main agent.

c) User-driven extension: Users can extend agents themselves with skills, prompt fragments, tools (including MCP servers), or slash commands — giving them control over what capabilities are available.

d) Capabilities (since 1.69): We now offer a way to encapsulate the various technical extension mechanisms into a user-visible concept. So instead of the user having to "activate delegation to the GitHub agent," it simply becomes "Activate GitHub." This abstracts the underlying technical approach into something more intuitive.

Practical Guidance

As I said, there's no clear-cut answer on which approach works best — it depends on many factors: what are the use cases, how large are the base prompts, how complex is the task, etc. But in our experience from various projects, it helps to consider the following key tradeoff:

Precision vs. usability without being explicit

The more reduced and focused an agent's capabilities are, the better it usually performs. However, this makes orchestration harder and potentially requires the user to understand which agent to use or which capability to enable.

So as a practical starting point:

• If the task is simple and you have a strong model, you might just get away with one agent that has everything it needs.
• Rather than using the original Orchestrator model have a super agent that is capable of covering the most important use cases. If you have completly non-overlapping global use cases, teach your users to select and agent (or have an agent with different modes). You might also use the Orchestrator in this case, but it has some down sides if it does not work 100%
• If the context gets too large or performance degrades, the next step is to extract some steps into sub-agents or skills.
• Which extraction mechanism works best depends on the nature of what you're extracting:
  • If it's a separate, repeated workflow with its own tools → lean toward a sub-agent (delegation)
  • If it's a capability that should be available throughout the whole session → lean toward a skill or capability

Hope that gives you a useful overview! That said, it's really hard to give more concrete guidance without knowing your particular use case in detail — the "right" approach depends heavily on what your agents actually do, how their capabilities overlap, how complex the tasks are, and what your users expect. If you can share more specifics about your setup, we're happy to dig deeper.

Best,
Jonas

[safisa]

Hi @JonasHelming
Thank you very much for the detailed response. I believe I need to try several approaches to determine which one works best.
Thanks again.