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 server supports command line flags for managing task prompts:
Display all available prompt templates with their descriptions:
clojure -M:mcp-tasks --list-prompts
Install prompt templates to .mcp-tasks/prompts/ directory:
# Install all available prompts
clojure -M:mcp-tasks --install-prompts
# Install specific prompts (comma-separated)
clojure -M:mcp-tasks --install-prompts simple,clarify-task
The --install-prompts command:
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 prompt:
.md file in .mcp-tasks/prompts/ directorydescription field (optional but recommended).md) becomes the category nameExample .mcp-tasks/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/prompts/ directory for .md filesBuilt-in prompts from resources/prompts/ serve as defaults. Custom prompts in .mcp-tasks/prompts/ override built-in prompts with the same name.
mcp-tasks has two types of prompts:
simple, medium, large). Stored in .mcp-tasks/prompts/<category>.md.mcp-tasks/story/prompts/<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/prompts/ directory:
.md files in .mcp-tasks/prompts/.md extension) becomes the category nameFor example, if you have:
.mcp-tasks/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/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/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/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 its execution prompts as MCP resources, enabling advanced use cases like prompt composition and inspection.
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-task
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 |