This guide describes how to customize mcp-tasks behavior and workflows beyond configuration file settings. For configuration options like git mode and branch management, see Configuration.
Customization focuses on adapting task execution workflows, categories, and metadata to match your team's processes, while configuration controls runtime behavior and feature flags.
For system-level settings like git integration, branch management, and worktree support, see the Configuration documentation. The .mcp-tasks.edn configuration file controls how the system operates, while the customizations described below control how tasks are defined and executed.
The mcp-tasks CLI provides commands for managing prompt templates and customizing workflows.
Display all available built-in prompts with their names, types, and descriptions:
# Human-readable output (default)
mcp-tasks prompts list
# JSON output
mcp-tasks prompts list --format json
# EDN output
mcp-tasks prompts list --format edn
The list command shows:
simple, medium, large)Example output:
Available Prompts:
Category Prompts (4):
simple Execute simple tasks with basic workflow
medium Execute medium complexity tasks with analysis, design...
large Execute large tasks with detailed analysis, design...
clarify-task Transform informal task instructions into clear...
Workflow Prompts (7):
execute-task Execute a task following category-specific workflow...
refine-task Refine a task to improve clarity and completeness
execute-story-child Execute the next task from a story's task list
create-story-tasks Break down a story into categorized, executable tasks
complete-story Mark a story as complete and archive it
create-story-pr Create a pull request for a completed story
review-story-impl... Review the implementation of a story
Total: 11 prompts (4 category, 7 workflow)
Install built-in prompt templates to local directories for customization:
# Install a single prompt
mcp-tasks prompts install simple
# Install multiple prompts
mcp-tasks prompts install simple medium execute-task
# JSON output for scripting
mcp-tasks prompts install simple --format json
The install command:
.mcp-tasks/category-prompts/.mcp-tasks/prompt-overrides/Example output:
Installing prompts...
✓ simple (category)
→ .mcp-tasks/category-prompts/simple.md
✓ execute-task (workflow)
→ .mcp-tasks/prompt-overrides/execute-task.md
Summary: 2 installed, 0 failed
Backward Compatibility: The system continues to read from deprecated locations (.mcp-tasks/prompts/ and .mcp-tasks/story/prompts/) with warnings. See Migration Guide for details.
Prompt templates define the execution workflow for tasks. mcp-tasks provides built-in prompts for common workflows, and you can create custom prompts to match your team's processes.
Prompts are stored as Markdown files with optional YAML frontmatter:
---
description: Execute simple tasks with basic workflow
---
- Analyze the task specification in the context of the project
- Plan an implementation approach
- Implement the solution
- Create a git commit with the code changes in the main repository
The frontmatter section (delimited by ---) contains metadata about the prompt. The content section (after frontmatter) contains the execution instructions that guide the AI agent.
Prompts support the following frontmatter fields:
description: Brief description of what the prompt does (used in MCP prompt listings and tool documentation)argument-hint: (Story prompts only) Defines expected arguments using <required> and [optional] syntaxExample frontmatter:
---
description: Execute medium complexity tasks with analysis, design, and user interaction
---
For story prompts with arguments:
---
description: Execute the next task from a story
argument-hint: <story-name> [additional-context...]
---
To create a custom category prompt:
.md file in .mcp-tasks/category-prompts/ directorydescription field (optional but recommended).md) becomes the category nameExample .mcp-tasks/category-prompts/research.md:
---
description: Execute research tasks with comprehensive analysis
---
- Define research questions and scope
- Identify relevant sources and documentation
- Gather information systematically
- Synthesize findings into actionable insights
- Document results with citations
- Identify gaps or areas requiring deeper investigation
Tasks assigned to the research category will use these execution instructions.
The system automatically discovers prompts by:
.mcp-tasks/category-prompts/ directory for .md files.mcp-tasks/prompt-overrides/ for custom workflow overridesBuilt-in prompts serve as defaults:
resources/category-prompts/ (simple.md, medium.md, large.md, clarify-task.md)resources/prompts/ (execute-task.md, refine-task.md, complete-story.md, etc.)Custom prompts override built-in prompts:
.mcp-tasks/category-prompts/<category>.md.mcp-tasks/prompt-overrides/<name>.mdmcp-tasks has two types of prompts:
simple, medium, large). Located in .mcp-tasks/category-prompts/<category>.md.mcp-tasks/prompt-overrides/<name>.mdCategories organize tasks by execution workflow. Each category corresponds to a prompt template that defines how tasks in that category should be executed.
Categories are automatically discovered by scanning the .mcp-tasks/category-prompts/ directory:
.md files in .mcp-tasks/category-prompts/.md extension) becomes the category nameFor example, if you have:
.mcp-tasks/category-prompts/
├── simple.md
├── medium.md
├── large.md
└── research.md
The system discovers four categories: simple, medium, large, and research.
To add a new category:
.mcp-tasks/category-prompts/<category-name>.md:category fieldThe category becomes immediately available for use in tasks. No additional configuration is required.
Category names should:
simple, complex, research, spike).md extensionExamples:
simple - Basic implementation tasksmedium - Tasks requiring analysis and designlarge - Complex tasks with multiple phasesresearch - Investigation and analysis tasksspike - Exploratory proof-of-concept tasksCategories and prompts have a 1:1 mapping:
.md)When you create a task with :category "research", the system:
.mcp-tasks/category-prompts/research.md.mcp-tasks/prompts/research.md (with warning)resources/category-prompts/research.mdTasks support custom metadata for tracking additional information beyond the core task fields.
The :meta field is a map of string keys to string values that can store arbitrary task information:
{:id 42
:title "Implement user authentication"
:category "large"
:meta {"priority" "high"
"estimate" "3 days"
"reviewer" "alice"
"component" "auth"}}
The :meta field is useful for:
Important: Both keys and values must be strings. Use string representations for other data types (e.g., "3" instead of 3).
The :relations field defines typed relationships between tasks. Each relation is a map with:
:id - Unique identifier for the relation:relates-to - ID of the related task:as-type - Type of relationshipAvailable relation types:
:blocked-by - This task is blocked by another task:related - General relationship without blocking semantics:discovered-during - This task was discovered while working on another taskExample:
{:id 100
:title "Implement payment processing"
:category "large"
:relations [{:id 1
:relates-to 99
:as-type :blocked-by}
{:id 2
:relates-to 87
:as-type :related}]}
This task (100) is blocked by task 99 and related to task 87.
While :meta and :relations support any valid data, consider establishing team conventions:
Priority levels:
:meta {"priority" "critical|high|medium|low"}
Time estimates:
:meta {"estimate" "1h|2d|1w"}
Component tags:
:meta {"component" "auth|api|ui"}
External tracking:
:meta {"jira-id" "PROJ-1234"
"github-issue" "123"}
Consistent conventions make it easier to filter, report, and manage tasks across your team.
Create .mcp-tasks/category-prompts/research.md:
---
description: Execute research tasks with systematic investigation
---
## Research Process
1. **Define Scope**
- Clarify research questions
- Identify constraints and boundaries
2. **Gather Information**
- Search documentation and code
- Review relevant examples and patterns
- Document sources
3. **Analyze Findings**
- Synthesize information
- Identify trade-offs
- Compare alternatives
4. **Document Results**
- Summarize key findings
- List recommendations
- Note open questions
5. **Commit Documentation**
- Add research notes to repository
- Link to relevant issues or tasks
Create a research task:
{:id 150
:title "Research authentication libraries for Clojure"
:description "Evaluate Ring-based auth libraries and OAuth providers"
:category "research"
:type :task
:meta {"area" "security"
"estimate" "2d"}
:relations []}
Create a task that blocks another task:
;; Infrastructure setup task
{:id 200
:title "Set up authentication database schema"
:category "simple"
:type :task
:meta {"priority" "high"}
:relations []}
;; Implementation task (blocked by infrastructure)
{:id 201
:title "Implement user registration endpoint"
:category "medium"
:type :feature
:meta {"priority" "high"}
:relations [{:id 1
:relates-to 200
:as-type :blocked-by}]}
Task 201 cannot proceed until task 200 is completed.
Track additional workflow information:
{:id 300
:title "Refactor payment processing module"
:category "large"
:type :chore
:meta {"component" "payments"
"technical-debt" "true"
"estimate" "1w"
"reviewer" "bob"
"risk-level" "medium"}
:relations []}
mcp-tasks exposes execution prompts and category metadata as MCP resources, enabling advanced use cases like prompt composition, inspection, and category discovery.
The categories resource provides a machine-readable list of all available task categories and their descriptions:
URI: resource://categories
Format: JSON
Structure:
{
"categories": [
{
"name": "simple",
"description": "Execute simple tasks with basic workflow"
},
{
"name": "medium",
"description": "Execute medium complexity tasks..."
}
]
}
The categories list is automatically generated from discovered category prompts in .mcp-tasks/category-prompts/ and includes descriptions extracted from YAML frontmatter. Categories are returned in alphabetical order by name.
Use cases:
Each category and story workflow has an associated prompt resource accessible via the prompt:// URI scheme:
Category prompts:
prompt://category-<category>
Examples:
prompt://category-simple - Simple task execution promptprompt://category-feature - Feature task execution promptprompt://category-bugfix - Bugfix task execution promptStory prompts:
prompt://refine-task
prompt://create-story-tasks
prompt://execute-story-child
Prompt resources include YAML frontmatter with metadata:
---
description: Execute simple tasks with basic workflow
---
Please complete the next simple task following these steps:
[... prompt content ...]
Frontmatter fields:
description (string) - Brief explanation of the prompt's purposeList all prompt resources:
Most MCP clients provide a way to list available resources. The exact method depends on your client.
Read a prompt resource:
Use your MCP client's resource reading capability with the prompt:// URI. For example, in Claude Code you might use tools to inspect prompt resources programmatically.
1. Prompt Composition
Build custom workflows by combining or referencing existing prompts:
# Custom prompt that references another
Execute the feature task, then follow the review process from prompt://review-checklist
2. Prompt Inspection
Understand what a category prompt does before executing tasks:
prompt://category-simple to see the simple task workflow3. Documentation
Generate workflow documentation by extracting prompt content and descriptions.
4. Tooling Integration
Build tools that discover and utilize mcp-tasks prompts programmatically via the MCP resource protocol.
Can you improve this documentation?Edit on GitHub
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |