Metadata-Version: 2.4
Name: scs-mcp
Version: 0.5.5
Summary: SCS - AI Capability Compiler. Turn scattered skills into verified, executable pipelines.
Project-URL: Homepage, https://github.com/lonyness/Skill-Compiler-System
Project-URL: Documentation, https://github.com/lonyness/Skill-Compiler-System#readme
Project-URL: Repository, https://github.com/lonyness/Skill-Compiler-System.git
Project-URL: Issues, https://github.com/lonyness/Skill-Compiler-System/issues
Project-URL: Changelog, https://github.com/lonyness/Skill-Compiler-System/releases
Author-email: SCS Team <scs-team@example.com>
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,claude-code,cline,compiler,cursor,mcp,skills,windsurf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.9
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# SCS — Skill Compiler System

**[中文版](README_CN.md)**

> **Turn scattered skills into reliable workflows**

You've collected many skill files. But when it's time to actually use them:

- *"Which ones do I need for this task?"*
- *"Can they chain together? Or will it break halfway?"*
- *"Why do I have to manually piece them together, with no way to know if it will work?"*

**The core problem**: Skills are defined separately, but they need to work together. Nobody builds the bridges.

---

## Core Concepts

Before diving in, understand these 3 key concepts:

### What is a Skill?

A **Skill** is a reusable capability definition. Think of it as a "function" in programming:

```
Skill: "Write PRD"
  - Input: User requirements (raw text)
  - Output: PRD document (structured)
  - Description: How to transform user input into a formal PRD
```

Each skill is a `.md` file in your agent's skills directory, defining what it does, what it needs, and what it produces.

### What is an Artifact?

An **Artifact** is the "data" that flows between skills — the input and output of each step.

```
[User Requirements] → Skill: Write PRD → [PRD Document] → Skill: Review PRD → [Validated PRD]
```

Artifacts have **types** (like PRDDocument, SourceCode, TestReport). SCS uses these types to match skills together — if skill A outputs `PRDDocument` and skill B takes `PRDDocument` as input, they can connect.

**Think of artifacts as typed variables that skills pass around.**

### What is an Execution Plan (DAG)?

An **Execution Plan** is a verified, step-by-step workflow. SCS generates these by:

1. Finding skills that can chain together (matching artifact types)
2. Ordering them correctly (inputs ready before outputs needed)
3. Checking feasibility (no circular dependencies, no missing inputs)
4. Showing you the full path before execution

**It's like Terraform Plan — preview with validation, before you commit.**

---

## Supported AI Agents

SCS works with these AI coding assistants:

| Agent | Skills Directory | How SCS Connects |
|-------|-----------------|------------------|
| **Claude Code** | `~/.claude/commands/` | MCP tools + Router skill |
| **Cursor** | `~/.cursor/rules/` | MCP tools + Router skill |
| **Windsurf** | `.windsurf/rules/` | MCP tools + Router skill |
| **Cline** | `.clinerules/` | MCP tools + Router skill |

**Key point**: SCS discovers skills from **all installed agents**, but each agent can only **invoke** skills in its own directory. If the recommended skill comes from another agent, you'll need to copy it or install that agent.

---

## One-Click Install

### Via PyPI (Recommended)

```bash
pip install scs-mcp
```

Then install to your agent:

```bash
# Install to Claude Code
scs install --agent claude_code

# Install to all supported agents
scs install --all

# Install to specific agent
scs install --agent cursor
scs install --agent windsurf
scs install --agent cline
```

**What gets installed**:
1. **8 MCP tools** — available in your agent's tool palette
2. **SCS Router skill** — guides your agent when to use SCS

After installation, restart your agent.

### Via GitHub

```bash
git clone https://github.com/lonyness/Skill-Compiler-System.git
cd Skill-Compiler-System
pip install -e .
scs install --agent claude_code
```

---

## 5-Minute Quick Start

### Step 1: Initialize SCS

In your AI agent, call:

```
scs_init()
```

SCS scans all skills across all installed agents and builds the connection graph.

### Step 2: Find Your Target

```
scs_list(type="artifacts")
```

This shows all artifact types you can produce. Pick one as your goal.

### Step 3: Get Optimal Path

```
scs_init(target="ValidatedPRD", prefer="balanced")
```

SCS finds the best path to your target:
- `prefer="fast"` — shortest path, fewest skills
- `prefer="quality"` — most thorough, includes validation steps
- `prefer="balanced"` — trade-off between speed and quality

### Step 4: Understand the Plan

```
scs_get(type="dag", id="plan_xxx")
```

See the full execution plan — each step, inputs, outputs, and why this path was chosen.

### Step 5: Execute

Follow the plan steps in order. Each step tells you:
- Which skill to invoke
- What input to provide
- What output to expect

---

## Tool Reference

| Tool | Purpose | When to Use |
|------|---------|-------------|
| `scs_init()` | Full initialization | First time, or after adding new skills |
| `scs_init(target=...)` | Path to specific goal | When you know what you want to produce |
| `scs_scan()` | Scan only, no compile | Large skill sets (2000+), avoid timeout |
| `scs_compile(target=...)` | Compile to plan | After scs_scan, when ready to generate plans |
| `scs_list(type=...)` | Browse inventory | Explore skills, artifacts, plans |
| `scs_get(type=..., id=...)` | View details | Deep dive into a specific item |
| `scs_diagnostics(plan_id=...)` | Debug plan | Understand why a path was chosen |
| `scs_clear()` | Reset state | Start fresh, clear all cached data |

---

## Best Practices

### 1. Define Skills with Clear Artifact Types

Good skill definition:

```markdown
---
inputs:
  - type: UserRequest
    description: Raw user requirements
outputs:
  - type: PRDDocument
    description: Structured product requirements
---
```

Avoid vague types like `Document` or `Text` — use specific types so SCS can match correctly.

### 2. Use Target-Driven Initialization

Instead of scanning all skills and browsing:

```
scs_init(target="ValidatedPRD")
```

This focuses SCS on finding the optimal path to your goal, much faster and more relevant.

### 3. Check Diagnostics Before Execution

```
scs_diagnostics(plan_id="plan_xxx")
```

This shows:
- Why each skill was selected
- What alternatives were considered
- Where gaps exist (if any)

### 4. Handle Large Skill Sets Properly

When you have 2000+ skills across multiple agents:

```
# Don't call scs_init() directly — it may timeout

# Use phased approach:
scs_scan()                        # ~90 seconds
scs_list(type="artifacts")        # Explore available outputs
scs_compile(target="YourTarget")  # ~30 seconds with target
```

---

## Real-World Example

**Scenario**: You want to generate a validated PRD from user requirements.

```
# 1. Initialize with target
scs_init(target="ValidatedPRD", prefer="balanced")

# 2. Get the plan
scs_list(type="dag")  # Find the plan ID
scs_get(type="dag", id="plan_abc123")

# 3. Plan shows:
Step 0: UserRequest → Step 1: WritePRD → Step 2: ReviewPRD → ValidatedPRD

# 4. Execute step by step:
- Step 1: Invoke "write_prd" skill with user requirements
  → Produces PRDDocument
- Step 2: Invoke "review_prd" skill with PRDDocument
  → Produces ValidatedPRD

# 5. Result: ValidatedPRD ready for use
```

SCS ensured:
- Skills are ordered correctly
- Each step's input is available from previous step
- No circular dependencies
- The path is optimal for "balanced" preference

---

## What SCS Does NOT Do

SCS is a **compiler/planner**, not an executor:

- ❌ Does not run skills for you
- ❌ Does not invoke AI agents
- ❌ Does not generate content directly

You (or your AI agent) execute the plan. SCS just gives you the verified blueprint.

---

## Coverage

SCS works across **8 industries, 176 artifact types**:

| Industry | Example Artifacts |
|----------|------------------|
| Software | Requirements, source code, test report, API spec |
| Legal | Contract, legal opinion, due diligence report |
| Marketing | Marketing plan, brand guidelines, ad copy |
| Finance | Financial report, invoice, ROI analysis |
| HR | Job description, resume, performance review |
| Research | Research paper, literature review, grant application |
| Content | Article, blog post, video script |
| Operations | Service ticket, SOP, incident report |

---

## Project Links

- **PyPI**: https://pypi.org/project/scs-mcp/
- **GitHub**: https://github.com/lonyness/Skill-Compiler-System
- **Issues**: https://github.com/lonyness/Skill-Compiler-System/issues

---

<p align="center">
  <strong>SCS — Compile skills, not chaos.</strong>
</p>