scs-mcp 0.5.4

SCS - AI Capability Compiler. Turn scattered skills into verified, executable pipelines.

SCS — Skill Compiler System

中文版

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)

pip install scs-mcp

Then install to your agent:

# 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

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:

---
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

---

SCS — Compile skills, not chaos.