Custom Prompts & Skills

Relevant source files

The following files were used as context for generating this wiki page:

• internal/engine/workflow/prompts/base.md
• internal/engine/workflow/prompts/execute-task.md
• internal/engine/workflow/prompts/plan-format.md
• internal/integrations/skills/loader.go
• internal/engine/workflow/plan.go
• internal/engine/workflow/execute.go

Custom Prompts and Skills form the core behavioral logic of M31A. The system utilizes a structured prompt registry and a skill discovery mechanism to define how the AI agent interacts with codebases, handles different workflow phases, and executes specific technical tasks. Prompts are treated as modular Markdown files that are injected into the LLM context based on the current active phase.

The system supports a variety of specialized prompt templates for phases like Initialize, Discuss, Plan, Execute, Verify, Runtime, and Ship. These templates ensure that the agent follows core principles such as the "Read-Before-Write Rule" and "Think before acting" pre-flight checks, while maintaining high code quality and consistency across various programming languages.
Sources: internal/engine/workflow/prompts/base.md:16-24, internal/engine/workflow/execute.go:374-380

Prompt Management Architecture

M31A uses a dynamic prompt injection system where specific behavioral instructions are appended to the system prompt depending on the workflow context. This modularity allows the agent to shift its persona and tool-usage strategy as it moves from high-level planning to low-level code execution.

Phase-Specific Injection

Each workflow phase is associated with a tailored subset of context and specific prompt templates:

• Plan Phase: Receives plan-format.md, context-awareness.md, and project intelligence.
• Execute Phase: Receives execute-task.md, tool-use.md, and the detailed implementation plan.
• Discuss Phase: Focuses on clarifying requirements via discuss-questions.md.

Sources: internal/engine/workflow/prompts/base.md:26-31, internal/engine/workflow/plan.go:420-425, internal/engine/workflow/execute.go:375-385

The Prompt Registry

The LoadPrompts function (referenced in testing) manages the collection of these templates. The system allows for dynamic overrides via a configured directory, enabling users to customize the agent's behavior for specific project types or organizational standards.
Sources: internal/engine/workflow/engine_test.go:323-335, README.md:278-280

The diagram shows how the system selectively assembles the system prompt by combining base instructions with phase-specific templates before sending the final context to the LLM.
Sources: internal/engine/workflow/execute.go:374-385, internal/engine/workflow/plan.go:420-430

Skills and Extension System

Skills in M31A are implemented as Markdown files containing YAML frontmatter and technical instructions. They are used to extend the agent's capabilities or provide specialized knowledge about certain frameworks (e.g., Next.js for website builds).

Skill Loading Mechanism

The skills package provides a loader that parses these files. Each skill file contains metadata defining its name, description, and whether it should be registered as a "slash command" in the TUI.

Field	Type	Description
name	string	The identifier for the skill/command.
description	string	Human-readable explanation of the skill's purpose.
slash	bool	If true, the skill is registered as a TUI slash command.
content	string	The actual behavioral instructions or prompt body.

Sources: internal/integrations/skills/loader.go:33-70

Skill Discovery Flow

The sequence illustrates how individual skill files are read and converted into actionable Skill objects by the loader.
Sources: internal/integrations/skills/loader.go:33-50

Core Instruction Modules

M31A relies on several critical prompt modules that are injected to maintain operational integrity.

Read-Before-Write Rule

A mandatory principle defined in base.md and enforced in execute-task.md. The agent is instructed that before creating or modifying any file, it must read:

• The target file (if it exists).
• Imported dependencies and interfaces.
• Callers and consumers of the file.
• Relevant configuration files (e.g., go.mod, package.json).

Sources: internal/engine/workflow/prompts/base.md:41-55, internal/engine/workflow/prompts/execute-task.md:31-36

Pre-Flight Tool Checks

Before every tool call, the agent must produce a structured mental pre-flight check covering:

1. GOAL: The specific purpose of the call.
2. TOOL: Why this tool is the correct choice.
3. SUCCESS: The expected output indicating success.
4. FAILURE: A contingency plan for failure.

Sources: internal/engine/workflow/prompts/base.md:35-40

Implementation Detail: Prompt Assembly

The buildExecuteContext and buildPlanContext functions are responsible for the programmatic assembly of these prompts. They fetch the required templates from the registry and combine them with dynamic project data.

// From internal/engine/workflow/execute.go:374
func (e *Engine) buildExecuteContext(ctx context.Context, task m31types.Task, tasks []m31types.Task, goal string) []m31types.Message {
	var messages []m31types.Message
	extras := []string{
        e.promptOrGet("tool-use"), 
        e.promptOrGet("execute-task"), 
        e.promptOrGet("context-awareness"), 
        e.promptOrGet("code-quality"), 
        e.promptOrGet("code-intelligence")
    }
	if e.ScopeIncludes("website") && e.promptOrGet("website-build") != "" {
		extras = append(extras, e.promptOrGet("website-build"))
	}
	systemPrompt := e.buildSystemPrompt(extras...)
    // ...
}

Sources: internal/engine/workflow/execute.go:374-384

Summary

The Custom Prompts & Skills system provides the cognitive framework for M31A. By separating behavioral instructions into modular Markdown files and utilizing a robust loader for skills, the project achieves a highly adaptable AI architecture. This ensures that the agent remains context-aware, follows strict coding standards, and can be extended with specialized domain knowledge without modifying the core engine logic.