skill2tools 0.1.0

TUI app to extract, classify, assemble, and test tools from Agent Skill definitions

skill2tools

A terminal UI application that extracts, classifies, assembles, and tests tools from Agent Skill definitions using AI.

Given a SKILL.md file (and optionally an agent.yaml), skill2tools uses an LLM via OpenRouter to identify every tool the skill requires, validates each against the Context7 library catalog, classifies them by integration type, generates implementation scaffolding, and runs automated tests to verify each tool works.

SKILL.md ──> Extract Tools ──> Validate (Context7) ──> Classify ──> Assemble ──> Test
                  AI                 MCP                  AI         Build/Config   pytest

Screenshots

AI Provider Setup — select and configure your LLM provider

Project Setup — select your skill file and agent definition

Features

• 8-screen TUI pipeline built with Textual — walk through each phase interactively, including dedicated setup and configuration screens
• Dual AI provider support — choose between OpenRouter (cloud) and vLLM (local/self-hosted) with automatic model discovery
• Initial setup wizard — first-run SetupScreen guides you through provider selection, connection testing, and model configuration
• Runtime configuration editor — ConfigScreen (press c) lets you view and switch AI provider settings without restarting
• AI-powered tool extraction — parses skill documents and identifies discrete tools with parameters, permissions, and data sources
• Context7 library validation — checks if tools match known libraries via the Context7 MCP server before classifying
• 4 tool classifications with confidence scoring — AVAILABLE (existing package), MCP (protocol server), API (HTTP endpoint), BIN (custom script), each with a 0.0–1.0 confidence score
• Implementation language detection — AI determines whether BIN tools should be scaffolded as Python or Shell
• Automated assembly — validates packages, generates MCP/API integration configs, scaffolds Python/Shell scripts for BIN tools
• Automated testing — generates and runs pytest tests per tool, reports pass/fail with detailed metrics (passed, failed, errors, skipped)
• Persistent state — all progress saved to .skill2tools/ directory; resume from any phase if interrupted
• Persistent provider configuration — provider settings saved to provider_config.yaml, no need to reconfigure on every run
• Unified LLM client — provider-agnostic abstraction layer that normalizes messages, handles auth, and supports streaming and JSON mode across providers
• Streaming AI output — watch the LLM work in real-time in the log panel
• File-based logging — all activity logged to .skill2tools/skill2tools.log for debugging and audit

Requirements

• Python 3.11+
• One of the following AI providers:
  • An OpenRouter API key for cloud-based inference
  • A running vLLM server for local/self-hosted inference
• (Optional) A Context7 API key for library validation

Installation

# Clone and install
git clone <repo-url> && cd skill2tools
python3 -m pip install -e "."

# Or just use the launcher (auto-installs)
./skill2tools.sh --skill your-skill.md

Quick Start

Using OpenRouter (cloud)

# Set your API key
export OPENROUTER_API_KEY="sk-or-..."

# Run with the sample skill
./skill2tools.sh --skill examples/sample_skill.md

# Run with a skill + agent definition
./skill2tools.sh --skill examples/sample_skill.md --agent examples/sample_agent.yaml

# Resume an interrupted session
./skill2tools.sh --resume

Using vLLM (local/self-hosted)

# Run with a local vLLM server
./skill2tools.sh --skill examples/sample_skill.md --provider vllm --vllm-url http://localhost:8000

# The setup wizard will auto-discover available models from your vLLM server

Or run directly with Python:

python3 -m skill2tools --skill examples/sample_skill.md --agent examples/sample_agent.yaml

CLI Options

Flag	Description	Default
--skill PATH	Path to SKILL.md file	(required)
--agent PATH	Path to agent.yaml file	(optional)
--resume	Resume from existing .skill2tools/ state	false
--provider PROVIDER	AI provider (openrouter or vllm)	openrouter
--openrouter-key KEY	OpenRouter API key	$OPENROUTER_API_KEY
--vllm-url URL	vLLM server base URL	(none)
--model MODEL	Model ID	anthropic/claude-sonnet-4
--project-dir DIR	Working directory for .skill2tools/	.

Keyboard Shortcuts

Key	Action
q	Quit (saves state)
c	Open configuration editor
Ctrl+S	Force-save state
?	Show help

Pipeline Phases

0. Setup (first run)

Select your AI provider (OpenRouter or vLLM), configure the connection, and test it. For vLLM, the app auto-discovers available models from your server. Configuration is persisted to provider_config.yaml so you only need to do this once.

1. Welcome

Select your SKILL.md file, optionally an agent.yaml, and name the project. The app creates the .skill2tools/ directory structure and copies your input files.

2. Analysis

The AI reads your skill document and extracts every discrete tool with its name, description, type hint, data source, permissions, and parameters. Output streams in real-time to the log panel.

3. Classification

Each tool is validated against the Context7 library catalog. Tools found in Context7 with a high score are classified as AVAILABLE. Others are sent to the AI for classification as MCP, API, or BIN. Each classification includes a confidence score (0.0–1.0). You can review and override any classification before proceeding.

Classification	Meaning	Assembly Action
AVAILABLE	Existing installable package	Verify import, write requirements.txt
MCP	MCP server integration needed	Generate mcp_config.yaml
API	External HTTP API integration	Generate api_config.yaml
BIN	Custom script to build	Generate Python or Shell script

4. Assembly

Tools are assembled based on their classification:

• AVAILABLE — checks if the package is importable, writes install instructions
• MCP — generates MCP server configuration (server URL, tool name, auth, transport)
• API — generates API integration config (endpoint, method, auth, request/response schema)
• BIN — generates a complete Python script or bash script, validates syntax

5. Testing

For each tool, the AI generates a classification-specific pytest test file and runs it:

• AVAILABLE — import test, interface check, basic usage
• MCP — config validation, field checks, connection test
• API — config validation, endpoint reachability, response format
• BIN — script exists, syntax valid, runs with --help, basic execution

6. Summary

Dashboard showing all tools, their classification, test results, and overall readiness percentage. Export the final tools.md catalog.

Input Formats

SKILL.md (Agent Skills Specification)

Follows the agentskills.io format:

---
name: my-skill
description: What this skill does and when to use it.
license: Apache-2.0
compatibility: Requires Python 3.11+
metadata:
  author: your-org
  version: "1.0"
allowed-tools: Bash(python:*) Read
---

# My Skill

## When to use this skill
...

## Steps
1. First step
2. Second step

## Tools needed
- **tool_name** -- what it does

agent.yaml (Optional)

Provides additional context about the agent that will use these tools:

agent_id: my_agent
name: My Agent
description: What this agent does
version: "1.0"
domain: my_domain
primary_model: anthropic/claude-sonnet-4
supported_intents:
  - domain.action.verb
tool_categories:
  - category_name
tool_names:
  - known_tool_1
  - known_tool_2

Output Structure

The app creates a .skill2tools/ directory with all state and artifacts:

.skill2tools/
  skill2tools.yaml              # Master state (phase, project metadata)
  provider_config.yaml          # Persisted AI provider configuration
  skill2tools.log               # Application activity log
  skill/
    SKILL.md                    # Copy of input skill
  agent/
    agent.yaml                  # Copy of input agent
  tools/
    tools.md                    # Generated tools catalog
    <tool_name>/
      tool.yaml                 # Tool metadata, classification, status
      implementation/           # Generated code (BIN tools)
        tool.py / tool.sh
        requirements.txt
      integration/              # Config files (MCP/API tools)
        mcp_config.yaml
        api_config.yaml
      tests/
        test_tool.py            # Auto-generated pytest test
        results.json            # Test execution results
  flow/
    execution.yaml              # Current phase and progress
    history.yaml                # Timestamped event log
  status/
    implementation.yaml         # Per-tool implementation status
    testing.yaml                # Per-tool test results

Generated tools.md Format

The output follows the camp-style tools catalog:

## tool_name

Description of what the tool does.

**Type:** api
**Data source:** REST API
**Permissions:** read_data, network_access
**Parameters:** query (string), limit (integer)
**Classification:** API

Building Standalone Executables

Build a standalone binary for your platform using PyInstaller:

# Build for current platform
./build.sh

# Output: dist/<platform>/skill2tools

For cross-platform builds, use the included GitHub Actions workflow which builds for Linux, macOS, and Windows on every tagged release:

git tag v0.1.0
git push --tags
# GitHub Actions builds dist artifacts for all 3 platforms

Project Structure

skill2tools/
  src/
    app.py                      # Textual App shell, screen navigation
    models/                     # Data models (skill, agent, tool, project, config)
    screens/                    # 8 TUI screens (setup, welcome through summary, config)
    services/                   # Business logic (LLM client, Context7, assembly, testing, logger)
    prompts/                    # LLM prompt templates for each AI call
    widgets/                    # Custom Textual widgets (file picker, tool table, log panel, phase indicator)
    state/                      # File-system state management
    styles.tcss                 # Textual CSS stylesheet
  examples/                     # Sample skill.md and agent.yaml
  tests/                        # Project tests
  skill2tools.sh                # Launcher script
  build.sh                      # PyInstaller build script
  .github/workflows/build.yml  # CI/CD for multi-platform builds

Environment Variables

Variable	Description
OPENROUTER_API_KEY	OpenRouter API key (required when using OpenRouter provider)
CONTEXT7_API_KEY	Context7 API key (optional, improves library validation)

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You are free to redistribute and modify it under the terms of the GPL-3.0. See the LICENSE file for the full license text.