Creating Custom Skills
Relevant source files
The following files were used as context for generating this wiki page:
Skills are predefined, reusable workflows that chain multiple Zen MCP tools together to perform complex, multi-step tasks within an AI development environment like Claude Code. They allow developers to encapsulate best-practice processes, such as a full feature development cycle or a security audit, into a single, invokable command. By creating custom skills, teams can standardize common workflows, improve efficiency, and ensure consistent quality assurance across projects.
This document outlines the structure and process for creating your own custom skills for the Zen MCP Server. The primary prerequisite is a configured Zen MCP Server, as skills rely on calling its underlying tools.
Sources: examples/skills/README.md:3-4, examples/skills/README.md:104-106, examples/skills/README.md:62-63
Skill Architecture
A skill is defined by a single SKILL.md file located within its own dedicated directory. This structure allows for easy management and installation.
Sources: examples/skills/README.md:49-52
File Structure
The required directory structure for a skill is straightforward:
skill-name/
└── SKILL.md
This diagram illustrates the basic structure.
Installation
Skills can be installed at the project level for team-wide access or at the user level for personal use across all projects.
This diagram shows the two installation paths.
Sources: examples/skills/README.md:7-21
Project-level Installation (Recommended for teams):
Copy the skill folder into the project's .claude/skills/ directory. This ensures all team members who pull the repository have access to the same set of skills.
# Execute from your project's root directory
mkdir -p .claude/skills
cp -r /path/to/zen-mcp-server/examples/skills/my-custom-skill .claude/skills/
Personal Installation:
Copy the skill folder to ~/.claude/skills/ to make it available across all your projects.
cp -r /path/to/zen-mcp-server/examples/skills/my-custom-skill ~/.claude/skills/
Sources: examples/skills/README.md:7-17
The SKILL.md File
The SKILL.md file is the core of a skill, containing both metadata (via YAML frontmatter) and the operational logic (via Markdown instructions).
Sources: examples/skills/SKILL_TEMPLATE.md:7-12, examples/skills/README.md:54-55
SKILL.md Structure
---
name: my-custom-skill
description: My custom workflow. Use when...
---
# My Custom Skill
## Instructions
1. Use [tool1] to [action1]
2. Use [tool2] to [action2]
3. Use [tool3] to [final_action]
## Examples
...
Sources: examples/skills/README.md:109-119
YAML Frontmatter
The frontmatter defines the skill's identity and discoverability.
| Parameter | Description |
|---|---|
name | A unique, machine-friendly name for the skill (e.g., full-feature-cycle). |
description | A brief summary of what the skill does and when it should be used. |
Sources: examples/skills/SKILL_TEMPLATE.md:8-9, examples/skills/full-feature-cycle/SKILL.md:2-3
Instructions Section
This section provides the step-by-step logic for the skill. Each step typically involves calling a Zen MCP tool. The instructions guide the AI agent on how to execute the workflow.
For example, the full-feature-cycle skill defines a four-step process:
- Plan: Use the
plannertool to break down the feature. - Implement: A manual step for the developer.
- Review: Use the
codereviewtool to check the implementation. - Validate: Use the
precommittool to validate changes.
Sources: examples/skills/full-feature-cycle/SKILL.md:40-55
This workflow can be visualized as follows:
Model Configuration
Skills can recommend specific AI models for optimal performance and allow users to specify a model at runtime.
Recommended Models:
The SKILL.md file can include a table of recommended models, explaining why each is a good fit for the skill's tasks.
| Alias | Recommended Reason |
|---|---|
pro | Strong comprehensive ability |
kimik | Good for general tasks |
flash | Suited for fast tasks |
Sources: examples/skills/full-feature-cycle/SKILL.md:13-20
Specifying a Model:
The user can override the default model choice. The skill's instructions should be written to pass this user-specified model to the underlying tools.
# Default model usage
Use planner to break down this feature...
# User-specified model
Use planner with model [USER_MODEL] to break down this feature.
Sources: examples/skills/full-feature-cycle/SKILL.md:42-46
The interaction flow for using a skill with a specified model is shown below.
Examples Section
It is best practice to include an Examples section in SKILL.md to demonstrate various use cases, such as implementing a new feature or performing a refactoring task. This helps users understand how to effectively prompt the skill.
Sources: examples/skills/full-feature-cycle/SKILL.md:57-58, examples/skills/test-generation/SKILL.md:51-52
Available Skills
The repository provides several pre-built skills that serve as excellent templates and powerful tools.
| Skill | Description | Tool Combination |
|---|---|---|
semantic-code-search | Semantic code search | index_code → search_code |
deep-debug | Deep problem debugging | search_code → debug → planner |
secure-review | Secure code review | codereview → secaudit → precommit |
multi-model-review | Collaborative review with multiple models | consensus + codereview + thinkdeep |
full-feature-cycle | Complete development cycle | planner → codereview → precommit |
architecture-decision | Architecture decision process | thinkdeep + consensus + planner |
test-generation | Test case generation | testgen → codereview |
Sources: examples/skills/README.md:34-46
Summary
Creating custom skills in Zen MCP allows for the automation and standardization of complex development workflows. By defining a simple SKILL.md file with clear instructions, tool chains, and examples, developers can create powerful, reusable assets for their teams. This modular approach enhances productivity and ensures that best practices are consistently applied across the development lifecycle.
Sources: examples/skills/README.md:3-4, README.md:65-68