Create MCP Skill

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

📚 Reference: See MCP CLI Guide 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:

bash

# 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:

bash

# 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:

bash

# 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

code

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

4. Write Skill Documentation

Template for SKILL.md:

markdown

---
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](../../.docs/mcp-cli.md)

## 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:

bash

# 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](../../.docs/mcp-cli.md)

## Setup

```bash
# TODO - Add installation

Quick Start (FASTEST)

Common Task

bash

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

bash

# Solution

EOF

Discover tools

mcp tools $SERVER_COMMAND

Test interactively

mcp shell $SERVER_COMMAND

code


## 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

bash

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

bash

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:

bash

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

•

Test basic command:

bash

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

•

Test multi-command:

bash

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

•

Test with cleanup:

bash

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 - 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 - Link to .docs/mcp-cli.md
•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)