mcp-execution-skill

Skill generation for MCP progressive loading. Generates Claude Code skill files (SKILL.md) from TypeScript tool files.

Installation

cargo add mcp-execution-skill

Or add to your Cargo.toml:

[dependencies]
mcp-execution-skill = "0.6"

[!IMPORTANT] Requires Rust 1.89 or later.

Usage

use mcp_execution_skill::{scan_tools_directory, build_skill_context};
use std::path::Path;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Scan TypeScript tool files from generated server directory
    let tools = scan_tools_directory(Path::new("~/.claude/servers/github")).await?;

    // Build skill generation context
    let context = build_skill_context("github", &tools, None);

    // Use context.generation_prompt with LLM to generate SKILL.md
    println!("Skill: {}", context.skill_name);
    println!("Tools: {}", context.tool_count);
    println!("Prompt:\n{}", context.generation_prompt);

    Ok(())
}

[!TIP] For optimal results, use the MCP server (mcp-execution-server) for skill generation. It leverages LLM capabilities to summarize tool descriptions, resulting in more concise skill files.

Features

• JSDoc Parsing - Extract metadata (@tool, @server, @category, @keywords) from TypeScript files
• Context Building - Structure tool information into categories for skill generation
• Template Rendering - Generate prompts using pre-compiled Handlebars templates
• Async Directory Scanning - Non-blocking file operations via tokio::fs

Architecture

TypeScript Files → Parser → Context Builder → Template Renderer → SKILL.md Prompt

1. Parser (parser.rs) - Extracts JSDoc metadata using pre-compiled regexes
2. Context Builder (context.rs) - Groups tools by category, generates examples
3. Template Renderer (template.rs) - Renders Handlebars prompt template

Examples

Parse a Single Tool File

use mcp_execution_skill::parse_tool_file;

let content = r#"
/**
 * @tool create_issue
 * @server github
 * @category issues
 * @keywords create,issue,new
 * @description Create a new GitHub issue
 */
"#;

let parsed = parse_tool_file(content, "createIssue.ts")?;
assert_eq!(parsed.name, "create_issue");
assert_eq!(parsed.category, Some("issues".to_string()));

Build Context with Hints

use mcp_execution_skill::build_skill_context;

// Add use-case hints for better context
let hints = vec!["managing pull requests", "code review"];
let context = build_skill_context("github", &tools, Some(&hints));

println!("Categories: {:?}", context.categories.len());

Types

Error Handling

use mcp_execution_skill::{ParseError, ScanError};

// ParseError - JSDoc parsing failures
// ScanError - Directory scanning issues (permissions, limits)

Security

[!NOTE] Built-in DoS protection for untrusted input.

• File Size Limit - Max 1MB per file
• File Count Limit - Max 500 files per directory
• Path Validation - Only scans .ts files, excludes _runtime/

Related Crates

This crate is part of the mcp-execution workspace:

• mcp-execution-core - Foundation types and traits
• mcp-execution-codegen - TypeScript code generation
• mcp-execution-files - Virtual filesystem
• mcp-execution-cli - CLI with skill command

MSRV Policy

Minimum Supported Rust Version: 1.89

MSRV increases are considered minor version bumps.

License

Licensed under either of Apache License 2.0 or MIT license at your option.