Metadata-Version: 2.4
Name: skill2tools
Version: 0.1.0
Summary: TUI app to extract, classify, assemble, and test tools from Agent Skill definitions
License-Expression: GPL-3.0-only
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: textual>=3.0
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: testing
Requires-Dist: pytest-json-report>=1.5; extra == 'testing'
Requires-Dist: pytest>=8.0; extra == 'testing'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/logo.png" alt="skill2tools" width="600">
</p>

# skill2tools

A terminal UI application that extracts, classifies, assembles, and tests tools from [Agent Skill](https://agentskills.io/specification) definitions using AI.

Given a `SKILL.md` file (and optionally an `agent.yaml`), skill2tools uses an LLM via [OpenRouter](https://openrouter.ai) to identify every tool the skill requires, validates each against the [Context7](https://context7.com) 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

<p align="center">
  <img src="assets/screenshot_02.png" alt="AI Provider Setup — choose between OpenRouter and vLLM" width="700">
  <br><em>AI Provider Setup — select and configure your LLM provider</em>
</p>

<p align="center">
  <img src="assets/screenshot_01.png" alt="Project Setup — configure SKILL.md, agent.yaml, and project name" width="700">
  <br><em>Project Setup — select your skill file and agent definition</em>
</p>

## Features

- **8-screen TUI pipeline** built with [Textual](https://textual.textualize.io) — walk through each phase interactively, including dedicated setup and configuration screens
- **Dual AI provider support** — choose between [OpenRouter](https://openrouter.ai) (cloud) and [vLLM](https://docs.vllm.ai) (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](https://openrouter.ai/keys) for cloud-based inference
  - A running [vLLM](https://docs.vllm.ai) server for local/self-hosted inference
- (Optional) A [Context7 API key](https://context7.com) for library validation

## Installation

```bash
# 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)

```bash
# 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)

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

```bash
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](https://agentskills.io/specification) format:

```markdown
---
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:

```yaml
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:

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

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

```bash
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](LICENSE) file for the full license text.
