Create MCP Skill

Guide for creating new skills that use MCP (Model Context Protocol) servers with optimized performance patterns.

📚 Reference: See MCP CLI Guide (this document) for detailed patterns and best practices.

Overview

This skill helps you create a new skill that uses an MCP server by:

Setting up the skill directory structure
Discovering available MCP tools
Creating optimized command patterns
Applying performance best practices

Prerequisites

MCP CLI installed (brew install mcp or go install github.com/f/mcptools/cmd/mcptools@latest)
Target MCP server available (npm package, binary, etc.)

Process

1. Discover Available Tools

First, explore what the MCP server offers:

# List all tools
mcp tools SERVER_COMMAND

# Get detailed JSON schema
mcp tools SERVER_COMMAND --format json

# Interactive exploration
mcp shell SERVER_COMMAND
# Type /h for help

Example:

# Chrome DevTools
mcp tools bunx -y chrome-devtools-mcp@latest

# Filesystem server
mcp tools npx @modelcontextprotocol/server-filesystem ~

2. Test Individual Tools

Test each tool before documenting:

# Template
echo -e 'TOOL_NAME {"param":"value"}\nexit' | timeout 30 mcp shell SERVER_COMMAND

# Example
echo -e 'navigate_page {"url":"https://example.com"}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Check for:

Required vs optional parameters
Empty parameter schema issues
Response format
Execution time

3. Create Skill Structure

skills/SKILL_NAME/
├── SKILL.md           # Main skill documentation
└── .examples/         # (Optional) Example outputs

4. Write Skill Documentation

Template for SKILL.md:

---
name: SKILL_NAME
description: Brief description of what this skill does and when to use it.
allowed-tools: Bash, Read, Write
---

# Skill Name

Brief overview.

**📚 See also:** MCP CLI Guide (this document)

## Setup

\`\`\`bash
# Installation instructions for the MCP server
\`\`\`

## Quick Start (FASTEST)

### Common Task 1

\`\`\`bash
pkill -9 -f "server-pattern" 2>/dev/null; sleep 1; \\
echo -e 'command1 {"param":"value"}\\ncommand2 {"param":"value"}\\nexit' | \\
timeout 30 mcp shell SERVER_COMMAND [FLAGS]
\`\`\`

### Common Task 2

\`\`\`bash
# Another optimized pattern
\`\`\`

**⚡ Pattern:** cleanup; sleep; echo commands | timeout shell

## Key Tools

- **tool1** - Description (required params: `param1`, `param2`)
- **tool2** - Description (optional params: `param1`)

## Important Notes

- Server-specific quirks
- Performance considerations
- Common gotchas

## Troubleshooting

**Problem: [Common issue]**

\`\`\`bash
# Solution
\`\`\`

Best Practices Checklist

When creating an MCP-based skill, ensure:

✅ Performance

Quick Start section at the top with copy-paste ready commands
All examples use the optimized pattern: cleanup; sleep; echo | timeout shell
Shell mode recommended over individual calls
Cleanup commands included (pkill pattern)
Timeout wrapper on all shell commands (30s default)

✅ Parameter Handling

Parameters passed directly (no {"arguments":{}} wrapper)
Tools with optional-only params documented with workaround
Empty parameter bug addressed where applicable
Example commands show correct parameter format

✅ Documentation

Reference to MCP CLI guide included
Server installation instructions provided
Quick start patterns for common tasks
Key tools listed with parameter requirements
Troubleshooting section for common issues
Performance tips highlighted

✅ Command Structure

Correct argument order: mcp call TOOL SERVER --params '{}'
Server flags properly positioned with -- separator
Exit command included in shell mode examples
One-liner format (no backslash continuations if possible)

Example: Chrome DevTools Skill

See skills/chrome-devtools/SKILL.md for a complete example that follows all best practices.

Key features:

Quick start patterns at the top
6-9x performance improvement documented
Optimized one-liners for common tasks
Comprehensive troubleshooting guide
References MCP CLI guide

Template Generator

Generate a basic skill structure:

# Set variables
SKILL_NAME="my-mcp-skill"
SERVER_COMMAND="bunx my-mcp-server@latest"
SERVER_PATTERN="my-mcp-server"

# Create directory
mkdir -p "skills/$SKILL_NAME"

# Create SKILL.md with template
cat > "skills/$SKILL_NAME/SKILL.md" << 'EOF'
---
name: SKILL_NAME
description: TODO - Add description
allowed-tools: Bash, Read, Write
---

# Skill Name

TODO - Add overview

**📚 See also:** MCP CLI Guide (this document)

## Setup

```bash
# TODO - Add installation

Quick Start (FASTEST)

Common Task

pkill -9 -f "SERVER_PATTERN" 2>/dev/null; sleep 1; \
echo -e 'COMMAND\nexit' | \
timeout 30 mcp shell SERVER_COMMAND

Key Tools

tool1 - TODO

Important Notes

TODO

Troubleshooting

Problem: Issue

# Solution

EOF

Discover tools

mcp tools $SERVER_COMMAND

Test interactively

mcp shell $SERVER_COMMAND


## Common Patterns

### Pattern 1: Single Command Check

```bash
pkill -9 -f "PATTERN" 2>/dev/null; sleep 1; \
echo -e 'TOOL {"param":"value"}\nexit' | \
timeout 30 mcp shell SERVER -- --isolated

Pattern 2: Multi-Command Debug

pkill -9 -f "PATTERN" 2>/dev/null; sleep 1; \
echo -e 'CMD1 {"p":"v"}\nCMD2 {"p":"v"}\nCMD3 {"p":"v"}\nexit' | \
timeout 30 mcp shell SERVER -- --isolated

Pattern 3: With Custom Flags

pkill -9 -f "PATTERN" 2>/dev/null; sleep 1; \
echo -e 'COMMAND\nexit' | \
timeout 30 mcp shell SERVER -- --flag1 --flag2=value

Testing Your Skill

Test cleanup pattern works:

pkill -9 -f "PATTERN" 2>/dev/null; sleep 1; echo "Cleanup OK"

Test basic command:

echo -e 'list_tools\nexit' | timeout 10 mcp shell SERVER

Test multi-command:

echo -e 'cmd1\ncmd2\ncmd3\nexit' | timeout 30 mcp shell SERVER

Test with cleanup:

pkill -9 -f "PATTERN" 2>/dev/null; sleep 1; \
echo -e 'cmd1\ncmd2\nexit' | timeout 30 mcp shell SERVER

Verify no hanging:
- Commands should complete within timeout
- Exit command should terminate session cleanly

Optimization Checklist

Compare your skill against the optimized pattern:

Aspect	Before	After
Commands per task	5-10	1
Manual cleanup	Yes	Automated
Failures from locks	Common	Zero
Execution time	60-90s	5-10s
Success rate	60-70%	100%

Resources

MCP CLI Guide (this document) - Complete MCP CLI reference
Chrome DevTools Skill - Reference implementation
MCP Documentation - Official MCP docs
mcptools GitHub - CLI tool source

Quick Reference

Every MCP skill should have:

Quick Start section - Copy-paste ready commands
Optimized pattern - cleanup; sleep; echo | timeout shell
Performance note - Document speed improvement
MCP CLI guide reference - MCP CLI patterns are documented in this skill
Troubleshooting - Common issues and solutions

Every command should:

Include cleanup (pkill -9 -f "PATTERN")
Wait after cleanup (sleep 1)
Use shell mode for 2+ commands
Have timeout wrapper
End with exit
Use correct parameter format (no "arguments" wrapper)

create-mcp-skill