zhongwei/gh-nemori-ai-skills-mcp-skill-creator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-nemori-ai-skills-mcp-ski…/skills/mcp-skill-creator/references/quick-start.md
Zhongwei Li 097db974e4 Initial commit
2025-11-30 08:42:37 +08:00

13 KiB
Raw Permalink Blame History

Quick Start Guide

This guide will help you create your first MCP-powered skill using the mcp-skill-creator meta-skill.

Prerequisites

  1. Python 3.10 or higher
  2. MCP SDK installed: 
    pip install mcp --break-system-packages
  3. Node.js (for running MCP servers via npx)

Overview

Creating an MCP-powered skill is a two-phase process:

Phase 1 (Programmatic): Generate MCP infrastructure using provided scripts

  • Introspect MCP servers to discover tools
  • Generate type-safe Python wrappers

Phase 2 (LLM-Driven): Create the skill following skill-creator principles

  • Analyze workflow and identify optimization opportunities
  • Write workflow scripts combining MCP tools
  • Embed user preferences and SOPs into SKILL.md
  • Package the final skill

Step-by-Step Process

Step 1: Gather Input from User

Collect the following information:

MCP Servers (required):

{
  "mcp_servers": [
    {
      "name": "puppeteer",
      "command": ["npx", "-y", "@modelcontextprotocol/server-puppeteer"]
    },
    {
      "name": "twitter",
      "command": ["npx", "-y", "@modelcontextprotocol/server-twitter"]
    }
  ]
}

Workflow Description (required):

  • User's step-by-step workflow
  • Can be natural language, numbered list, or sequential narrative
  • Example: "First I visit the official website, then check Twitter and Reddit, finally create a report"

Preferences (optional):

  • "I prefer quantitative metrics over qualitative descriptions"
  • "Recent information is more valuable than old"
  • "Always cross-reference claims"

SOPs (optional):

  • "Start with official sources before checking community feedback"
  • "Cite all sources in the final report"
  • "Highlight contradictions between official and community perspectives"

Step 2: Generate MCP Infrastructure (Programmatic)

2.1 Create MCP Configuration File

# Save MCP server config
cat > mcp_config.json << EOF
{
  "servers": [
    {
      "name": "puppeteer",
      "command": ["npx", "-y", "@modelcontextprotocol/server-puppeteer"]
    },
    {
      "name": "twitter",  
      "command": ["npx", "-y", "@modelcontextprotocol/server-twitter"]
    }
  ]
}
EOF

2.2 Introspect MCP Servers

python scripts/mcp_introspector.py mcp_config.json introspection.json

This discovers all available tools from the MCP servers and saves them to introspection.json.

2.3 Generate Tool Wrappers

mkdir -p my-skill/scripts
python scripts/generate_mcp_wrappers.py introspection.json my-skill

This creates:

  • my-skill/scripts/mcp_client.py - Base MCP client
  • my-skill/scripts/tools/<server>/<tool>.py - Type-safe wrappers for each tool
  • my-skill/scripts/tools/<server>/__init__.py - Package initialization

Generated structure:

my-skill/
└── scripts/
    ├── mcp_client.py
    └── tools/
        ├── puppeteer/
        │   ├── __init__.py
        │   ├── fetch_page.py
        │   └── screenshot.py
        └── twitter/
            ├── __init__.py
            └── search_tweets.py

Step 3: Analyze Workflow (LLM-Driven)

Now use Claude to analyze the user's workflow description:

Ask yourself:

  • What are the distinct workflow steps?
  • Which steps are data fetching (candidates for parallelization)?
  • Which steps are data processing (candidates for execution environment filtering)?
  • Are there any loops, conditionals, or polling patterns?
  • What intermediate state needs to be preserved?

Example Analysis:

User workflow: "Research products by checking official site, Twitter, Reddit, then create report"

Analysis:

  • Step 1: Fetch official website (data fetch)
  • Step 2: Search Twitter (data fetch - can parallelize with step 3)
  • Step 3: Search Reddit (data fetch - can parallelize with step 2)
  • Step 4: Aggregate data (data processing - filter in execution env)
  • Step 5: Generate report (output)

Optimization opportunities:

  • Parallel execution: Steps 2-3
  • Data filtering: Step 4 (process 1000s of posts, return top 10)
  • Context efficiency: Return summary, not raw data

Step 4: Plan Skill Contents (LLM-Driven)

Based on the workflow analysis, decide what to include:

Should you create a script?

  • ✅ Yes: Multi-step workflow, parallel execution opportunities, data filtering needed
  • ❌ No: Single tool call, high variability, exploratory task

For each script, plan:

  • Purpose and scope
  • Which MCP tools it uses
  • Optimization patterns (parallel, filtering, control flow)
  • Parameters and return value

Example Plan:

Script: scripts/workflows/product_research_pipeline.py

  • Purpose: Complete product research workflow
  • MCP tools: puppeteer.fetch_page, twitter.search_tweets, reddit.search_discussions
  • Optimizations:
    • Parallel execution of Twitter + Reddit searches
    • Data filtering: Extract top 10 insights from 1000+ posts
    • Return summary, not raw data
  • Parameters: product_url, product_name
  • Returns: {features, sentiment, highlights}

Step 5: Implement the Skill (LLM-Driven)

5.1 Create Workflow Scripts

Write my-skill/scripts/workflows/product_research_pipeline.py:

import asyncio
from scripts.tools import puppeteer, twitter, reddit

async def product_research_pipeline(product_url: str, product_name: str):
    """
    Complete product research workflow
    
    Optimizations:
    - Parallel Twitter + Reddit searches (2x faster)
    - Data filtering in execution environment
    - Returns summary, not raw data
    """
    
    # Fetch official website
    official = await puppeteer.fetch_page(product_url)
    
    # Parallel social media research
    twitter_data, reddit_data = await asyncio.gather(
        twitter.search_tweets(f'"{product_name}"'),
        reddit.search_discussions(product_name, subreddits=['SaaS'])
    )
    
    # Process in execution environment (not in context)
    key_features = extract_features(official, top_n=10)
    sentiment = analyze_sentiment([twitter_data, reddit_data])
    highlights = extract_highlights(twitter_data + reddit_data, top_n=5)
    
    # Return summary only
    return {
        'key_features': key_features,
        'sentiment': sentiment,
        'highlights': highlights,
        'mention_count': len(twitter_data) + len(reddit_data)
    }


def extract_features(html: str, top_n: int) -> list:
    """Extract key features from website HTML"""
    # TODO: Implement feature extraction logic
    return []

def analyze_sentiment(social_data: list) -> dict:
    """Analyze sentiment from social media posts"""
    # TODO: Implement sentiment analysis
    return {'score': 0, 'summary': ''}

def extract_highlights(posts: list, top_n: int) -> list:
    """Extract most relevant highlights from posts"""
    # TODO: Implement highlight extraction
    return []

Key principles:

  • Use async/await for IO-bound operations
  • Combine related MCP calls into single scripts
  • Filter/aggregate data in execution environment
  • Return summaries, not raw data
  • Include helper functions for data processing

5.2 Write SKILL.md

Create my-skill/SKILL.md embedding user preferences and SOPs:

---
name: product-research-workflow
description: Automated product research integrating official sources and social platforms with emphasis on quantitative metrics and recent information
---

# Product Research Workflow

Efficiently research internet products by gathering data from official sources 
and social platforms, following your standard research methodology.

## Workflow Overview

This skill implements your research process with built-in optimizations:

1. **Official Source Analysis**: Visit product website to extract key features 
   and positioning (your SOP: always start with official sources)

2. **Social Intelligence Gathering**: Search Twitter and Reddit in parallel 
   for community feedback (optimized: 2x faster than sequential)

3. **Cross-Reference Analysis**: Identify contradictions between official claims 
   and community feedback (your preference: highlight discrepancies)

4. **Report Generation**: Create comprehensive report emphasizing quantitative 
   metrics like ratings and user counts (your preference: quant > qual)

## Quick Start

```python
from scripts.workflows import product_research_pipeline

report = await product_research_pipeline(
    product_url='https://example.com',
    product_name='ExampleApp'
)

Available Workflows

product_research_pipeline

Use when: Researching any new internet product or SaaS tool

Location: scripts/workflows/product_research_pipeline.py

Optimizations:

  • 2x faster via parallel social media gathering
  • Context-efficient: processes 1000s of posts, returns top 10 insights
  • Recent info prioritized (aligns with your preference)

Usage:

from scripts.workflows import product_research_pipeline

result = await product_research_pipeline(
    product_url='https://product.com',
    product_name='ProductName'
)

# Result structure:
# {
#   'key_features': ['Feature 1', 'Feature 2', ...],
#   'sentiment': {'score': 0.75, 'summary': '...'},
#   'highlights': ['Highlight 1', ...],
#   'mention_count': 247
# }

MCP Tools Available

puppeteer

Tools: 5 available

Location: scripts/tools/puppeteer/

Key tools: fetch_page, screenshot, pdf_export

Discovery: Use ls scripts/tools/puppeteer/ to see all tools

twitter

Tools: 3 available

Location: scripts/tools/twitter/

Key tools: search_tweets, get_user_timeline

Discovery: Use ls scripts/tools/twitter/ to see all tools

Performance Notes

  • Token reduction: 98.7% fewer tokens vs loading all tools upfront
  • Speed: 2x faster via parallel execution
  • Context efficiency: Processes large datasets, returns summaries

Advanced Usage

For custom workflows, combine individual MCP tools:

from scripts.tools import puppeteer, twitter

# Custom combination
official_data = await puppeteer.fetch_page(url)
tweets = await twitter.search_tweets(query)

# Your own processing logic...


**Critical**: Notice how preferences and SOPs are embedded into the workflow description, not as separate sections.

### Step 6: Package and Deliver

Once the skill is complete:

```bash
python /mnt/skills/public/skill-creator/scripts/package_skill.py my-skill

This creates my-skill.skill file ready for distribution.

Complete Example

Let's create a product research skill from start to finish:

1. Gather Input

User provides:

MCP Servers: puppeteer, twitter
Workflow: "Visit official site, check Twitter, create report"
Preferences: "Quantitative metrics preferred, recent info valued"
SOPs: "Always start with official sources"

2. Generate Infrastructure

# Create config
cat > mcp_config.json << 'EOF'
{
  "servers": [
    {"name": "puppeteer", "command": ["npx", "-y", "@modelcontextprotocol/server-puppeteer"]},
    {"name": "twitter", "command": ["npx", "-y", "@modelcontextprotocol/server-twitter"]}
  ]
}
EOF

# Introspect
python scripts/mcp_introspector.py mcp_config.json introspection.json

# Generate wrappers
mkdir -p product-research-skill
python scripts/generate_mcp_wrappers.py introspection.json product-research-skill

3-5. Create Skill (LLM)

Claude analyzes workflow, creates workflow script, writes SKILL.md with embedded preferences.

6. Package

python /mnt/skills/public/skill-creator/scripts/package_skill.py product-research-skill

Done! You now have product-research-skill.skill.

Tips for Success

Writing Good Workflow Descriptions

✅ Good:

  • "First I visit the official website, then check Twitter and Reddit, finally create a report"
  • Numbered steps with clear actions
  • Mentions data sources explicitly

❌ Bad:

  • "I research products" (too vague)
  • No clear sequence
  • Missing data sources

Embedding Preferences Effectively

✅ Good: Weave into workflow guidance

This skill gathers quantitative metrics (ratings, user counts) from multiple 
sources, prioritizing recent information over older reviews.

❌ Bad: Separate section

## User Preferences
- Likes quantitative metrics
- Prefers recent info

When to Create Scripts vs Guidance

Create Scripts:

  • 3+ step workflows
  • Parallel execution opportunities
  • Data filtering needs
  • Repeated code patterns

Use Text Guidance:

  • Ad-hoc exploration
  • High variability
  • Simple tool usage
  • Flexibility needed

Troubleshooting

MCP Connection Errors

# Test MCP server manually
npx -y @modelcontextprotocol/server-puppeteer

# Check output for errors

Import Errors

# Ensure MCP SDK installed
pip install mcp --break-system-packages

# Verify Python path
export PYTHONPATH="${PYTHONPATH}:$(pwd)/my-skill"

Generated Code Issues

  • Review generated wrappers in scripts/tools/
  • Customize as needed (they're templates)
  • Test scripts before packaging

Next Steps

  • Read references/mcp-best-practices.md for advanced patterns
  • Explore references/example-config.json for complete examples
  • Customize generated scripts for your specific needs
  • Build a library of workflow skills!

Getting Help

Reference in New Issue View Git Blame Copy Permalink