Custom System Prompts: Skills Added, Tools Missing

Ever felt like you're talking to a brilliant assistant, but they're missing a piece of crucial information? That's kind of what's happening with our coding agent when you dive into custom system prompts. You might be meticulously crafting your instructions, adding all sorts of wonderful skills to guide your AI, but here's the rub: the descriptions for the tools themselves aren't making the cut into your custom prompt. It's a bit like handing your chef a recipe but forgetting to mention the oven they're supposed to use! This inconsistency can lead to some head-scratching moments and potentially unpredictable behavior from your AI. Let's unpack why this is happening and what we can do about it.

The Problem: A Tale of Two Prompt Branches

When we use a custom system prompt, denoted by the --system-prompt flag, we expect a certain level of control. However, the agent exhibits inconsistent behavior regarding what gets automatically appended to this prompt. On one hand, skills descriptions are faithfully added to your custom prompt, provided the read tool is available. This is great! It means your AI knows about the specific abilities you've imbued it with. But here's the kicker: tool descriptions are not added. This is a stark contrast to the default system prompt behavior. In the default setup, the agent meticulously includes descriptions for both tools and skills. This comprehensive approach helps the model understand the full spectrum of its capabilities. When you switch to a custom prompt, this auto-augmentation of tool descriptions disappears, leaving a gap in the model's understanding within the prompt text itself. While the tools still function because they're passed separately via the tools parameter in the API call, the AI doesn't get to see their descriptions directly in the system prompt. This disconnect is not just a minor oversight; it’s a potential source of confusion and can make the AI's behavior feel less predictable than it should be. Imagine trying to navigate a new city with a map that only shows you the parks and not the roads – you know there are roads, but you don't have the crucial directional information readily available.

Where the Disconnect Happens: Code Unpacked

To truly understand this inconsistency, let's peek under the hood at the code responsible for building these system prompts. Specifically, the buildSystemPrompt() function located in packages/coding-agent/src/core/system-prompt.ts reveals the distinct paths taken for custom versus default prompts.

The Custom Prompt Path (Lines 136-165)

When a custom prompt (resolvedCustomPrompt) is detected, the code embarks on a specific route. It starts by incorporating the custom prompt text. Then, it appends any context files, as expected. The crucial part comes next: an if condition checks if skills are enabled and if the read tool is available. If both conditions are met, the loadSkills() function is called, and the resulting skills are formatted and appended to the prompt using formatSkillsForPrompt(skills). This is where the skills descriptions are added. However, in this entire custom prompt branch, there is no corresponding code that adds the tool descriptions. They are simply left out of the system prompt text.

The Default Prompt Path (Lines 167+)

Now, let's look at what happens when you don't provide a custom prompt. The agent falls back to its default behavior. First, it constructs a toolsList. This list is meticulously built by mapping over the selectedTools (or defaulting to a standard set like `[