feat(coding-agent): add template variables to custom system prompts

packages/coding-agent/CHANGELOG.md

@@ -9,6 +9,7 @@
 
 ### Added
 
+- Template variables (`{{tools}}`, `{{context}}`, `{{skills}}`) for custom system prompts in SYSTEM.md, allowing precise control over where dynamic content is injected
 - `markdown.codeBlockIndent` setting to customize code block indentation in rendered output
 - Extension package management with `pi install`, `pi remove`, `pi update`, and `pi list` commands ([#645](https://github.com/badlogic/pi-mono/issues/645))
 - `/reload` command to reload extensions, skills, prompts, and themes ([#645](https://github.com/badlogic/pi-mono/issues/645))

packages/coding-agent/src/core/agent-session.ts

@@ -233,6 +233,11 @@ export class AgentSession {
 	// Base system prompt (without extension appends) - used to apply fresh appends each turn
 	private _baseSystemPrompt = "";
 
+	// Track whether context/skills were injected into the system prompt
+	// Used by UI to conditionally show "Loaded context/skills"
+	private _contextInjected = true;
+	private _skillsInjected = true;
+
 	constructor(config: AgentSessionConfig) {
 		this.agent = config.agent;
 		this.sessionManager = config.sessionManager;
@@ -583,14 +588,20 @@ export class AgentSession {
 		const loadedSkills = this._resourceLoader.getSkills().skills;
 		const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;
 
-		return buildSystemPrompt({
+		const result = buildSystemPrompt({
 			cwd: this._cwd,
 			skills: loadedSkills,
 			contextFiles: loadedContextFiles,
 			customPrompt: loaderSystemPrompt,
 			appendSystemPrompt,
 			selectedTools: validToolNames,
 		});
+
+		// Track injection state for UI display
+		this._contextInjected = result.contextInjected;
+		this._skillsInjected = result.skillsInjected;
+
+		return result.prompt;
 	}
 
 	// =========================================================================
@@ -1018,6 +1029,16 @@ export class AgentSession {
 		}));
 	}
 
+	/** Whether context files were injected into the system prompt */
+	get contextInjected(): boolean {
+		return this._contextInjected;
+	}
+
+	/** Whether skills were injected into the system prompt */
+	get skillsInjected(): boolean {
+		return this._skillsInjected;
+	}
+
 	get resourceLoader(): ResourceLoader {
 		return this._resourceLoader;
 	}

packages/coding-agent/src/core/system-prompt.ts

@@ -31,8 +31,17 @@ export interface BuildSystemPromptOptions {
 	skills?: Skill[];
 }
 
+export interface BuildSystemPromptResult {
+	/** The built system prompt */
+	prompt: string;
+	/** Whether context files were injected (always true for default prompt, depends on {{context}} for custom) */
+	contextInjected: boolean;
+	/** Whether skills were injected (always true for default prompt, depends on {{skills}} for custom) */
+	skillsInjected: boolean;
+}
+
 /** Build the system prompt with tools, guidelines, and context */
-export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): string {
+export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): BuildSystemPromptResult {
 	const {
 		customPrompt,
 		selectedTools,
@@ -63,30 +72,48 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 	if (customPrompt) {
 		let prompt = customPrompt;
 
-		if (appendSection) {
-			prompt += appendSection;
+		// Template variable replacement (opt-in injection)
+		// No template variables = full replacement mode (no automatic appending)
+		const contextInjected = prompt.includes("{{context}}");
+		const skillsInjected = prompt.includes("{{skills}}");
+
+		if (prompt.includes("{{tools}}")) {
+			const tools = selectedTools || ["read", "bash", "edit", "write"];
+			const toolsList =
+				tools.length > 0
+					? tools.map((t) => `- ${t}: ${toolDescriptions[t] ?? "Custom tool"}`).join("\n")
+					: "(none)";
+			prompt = prompt.replace("{{tools}}", toolsList);
 		}
 
-		// Append project context files
-		if (contextFiles.length > 0) {
-			prompt += "\n\n# Project Context\n\n";
-			prompt += "Project-specific instructions and guidelines:\n\n";
-			for (const { path: filePath, content } of contextFiles) {
-				prompt += `## ${filePath}\n\n${content}\n\n`;
+		if (contextInjected) {
+			let contextStr = "";
+			if (contextFiles.length > 0) {
+				contextStr = "# Project Context\n\n";
+				contextStr += "Project-specific instructions and guidelines:\n\n";
+				for (const { path: filePath, content } of contextFiles) {
+					contextStr += `## ${filePath}\n\n${content}\n\n`;
+				}
 			}
+			prompt = prompt.replace("{{context}}", contextStr);
 		}
 
-		// Append skills section (only if read tool is available)
-		const customPromptHasRead = !selectedTools || selectedTools.includes("read");
-		if (customPromptHasRead && skills.length > 0) {
-			prompt += formatSkillsForPrompt(skills);
+		if (skillsInjected) {
+			const customPromptHasRead = !selectedTools || selectedTools.includes("read");
+			const skillsStr = customPromptHasRead && skills.length > 0 ? formatSkillsForPrompt(skills) : "";
+			prompt = prompt.replace("{{skills}}", skillsStr);
+		}
+
+		// Append section always applies (for --append-system-prompt)
+		if (appendSection) {
+			prompt += appendSection;
 		}
 
-		// Add date/time and working directory last
+		// Add date/time and working directory last (always)
 		prompt += `\nCurrent date and time: ${dateTime}`;
 		prompt += `\nCurrent working directory: ${resolvedCwd}`;
 
-		return prompt;
+		return { prompt, contextInjected, skillsInjected };
 	}
 
 	// Get absolute paths to documentation and examples
@@ -176,13 +203,15 @@ Pi documentation (read only when the user asks about pi itself, its SDK, extensi
 	}
 
 	// Append skills section (only if read tool is available)
-	if (hasRead && skills.length > 0) {
+	const skillsInjected = hasRead;
+	if (skillsInjected && skills.length > 0) {
 		prompt += formatSkillsForPrompt(skills);
 	}
 
 	// Add date/time and working directory last
 	prompt += `\nCurrent date and time: ${dateTime}`;
 	prompt += `\nCurrent working directory: ${resolvedCwd}`;
 
-	return prompt;
+	// Default prompt always injects context, skills depend on read tool
+	return { prompt, contextInjected: true, skillsInjected };
 }

packages/coding-agent/src/modes/interactive/interactive-mode.ts

@@ -646,18 +646,26 @@ export class InteractiveMode {
 			return;
 		}
 
-		const contextFiles = this.session.resourceLoader.getAgentsFiles().agentsFiles;
-		if (contextFiles.length > 0) {
-			const contextList = contextFiles.map((f) => theme.fg("dim", `  ${this.formatDisplayPath(f.path)}`)).join("\n");
-			this.chatContainer.addChild(new Text(theme.fg("muted", "Loaded context:\n") + contextList, 0, 0));
-			this.chatContainer.addChild(new Spacer(1));
+		// Only show context files if they were actually injected into the system prompt
+		if (this.session.contextInjected) {
+			const contextFiles = this.session.resourceLoader.getAgentsFiles().agentsFiles;
+			if (contextFiles.length > 0) {
+				const contextList = contextFiles
+					.map((f) => theme.fg("dim", `  ${this.formatDisplayPath(f.path)}`))
+					.join("\n");
+				this.chatContainer.addChild(new Text(theme.fg("muted", "Loaded context:\n") + contextList, 0, 0));
+				this.chatContainer.addChild(new Spacer(1));
+			}
 		}
 
-		const skills = this.session.skills;
-		if (skills.length > 0) {
-			const skillList = skills.map((s) => theme.fg("dim", `  ${this.formatDisplayPath(s.filePath)}`)).join("\n");
-			this.chatContainer.addChild(new Text(theme.fg("muted", "Loaded skills:\n") + skillList, 0, 0));
-			this.chatContainer.addChild(new Spacer(1));
+		// Only show skills if they were actually injected into the system prompt
+		if (this.session.skillsInjected) {
+			const skills = this.session.skills;
+			if (skills.length > 0) {
+				const skillList = skills.map((s) => theme.fg("dim", `  ${this.formatDisplayPath(s.filePath)}`)).join("\n");
+				this.chatContainer.addChild(new Text(theme.fg("muted", "Loaded skills:\n") + skillList, 0, 0));
+				this.chatContainer.addChild(new Spacer(1));
+			}
 		}
 
 		const skillWarnings = this.session.skillWarnings;