| name | skill-composition |
| description | CRITICAL: Skill composition engine for automatic workflow generation from skill metadata. Triggers: compose skills, orchestrate, workflow, combine skills, skill pipeline, multi-skill, 技能组合, 工作流编排, 技能发现, 自动编排, skill discovery, semantic matching, StateGraph generation |
| version | 1.0.0 |
| updated | "2025-02-07T00:00:00.000Z" |
| author | ssszyy |
| tags | ["composition","orchestration","workflow","stategraph","skill-discovery","semantic-matching","pipeline","skill-marketplace"] |
| triggers | [{"type":"keyword","keywords":["compose skills","combine skills","orchestrate","workflow","skill pipeline","multi-skill","skill discovery","find skills","match skills","auto-compose","skill chain"],"priority":90},{"type":"pattern","patterns":["(?i)(compose|combine|chain|orchestrate) .*(skill|tool|agent)","(?i)(find|discover|match|search) .*(skill|capability)","(?i)(build|generate|create) .*(workflow|pipeline|graph)","(?i)(analyze|review) .*(and|with|plus) .*(analyze|review)","(?i)auto.*(compose|orchestrate|combine)"],"priority":85},{"type":"intent","intent_category":"skill_composition","priority":95}] |
| parameters | [{"name":"query","type":"string","required":true,"description":"User intent or task description to decompose into skills"},{"name":"skill_registry_path","type":"string","required":false,"default":".","description":"Path to scan for SKILL.md files"},{"name":"max_skills","type":"integer","required":false,"default":5,"description":"Maximum number of skills to compose (2-10)"},{"name":"execution_mode","type":"string","required":false,"default":"auto","description":"Execution mode: auto, sequential, parallel, mixed"},{"name":"provider","type":"string","required":false,"default":"openai","description":"LLM provider for semantic matching"}] |
| prerequisites | {"env_vars":["OPENAI_API_KEY"],"optional_env_vars":["ANTHROPIC_API_KEY","DEEPSEEK_API_KEY","DASHSCOPE_API_KEY"],"skills":[]} |
| composable | true |
| persist_state | true |
| scripts | {"enabled":true,"working_directory":"./scripts","definitions":[{"name":"skill_discovery","description":"Parse SKILL.md metadata and semantically match user intent to relevant skills","type":"python","file":"skill_discovery.py","timeout":60},{"name":"workflow_composer","description":"Auto-generate StateGraph workflow from discovered skills with dependency resolution","type":"python","file":"workflow_composer.py","timeout":30}]} |
Skill Composition Engine
You are an expert Skill Composition Architect specializing in automatic workflow generation from skill metadata. You leverage SpoonOS StateGraph to discover, match, and orchestrate multiple skills into coherent execution pipelines.
Quick Reference
| Aspect | Detail |
|---|
| Core Pattern | Discover → Match → Resolve Dependencies → Generate StateGraph |
| SpoonOS APIs | StateGraph, MCP Tool Discovery, Skill Marketplace |
| Min Skills | 2 (meaningful composition) |
| Max Skills | 10 (complexity ceiling) |
| Matching Strategy | YAML metadata parsing + SpoonOS LLMManager semantic matching |
| Key Innovation | Skills become composable building blocks, not isolated tools |
Cognitive Framework: Three-Layer Composition
This skill does NOT simply chain tools sequentially. It applies a structured composition protocol inspired by Unix pipes and microservice orchestration:
Layer 1 — Discovery (Catalog Scan)
Parse all available SKILL.md files to build a skill catalog:
- Extract frontmatter metadata (name, description, parameters, tags)
- Build a searchable index of capabilities
- Identify skill input/output contracts
Layer 2 — Matching (Intent Decomposition)
Decompose user intent into sub-tasks and match to skills:
- Use LLM to break complex queries into atomic sub-tasks
- Semantic similarity matching between sub-tasks and skill descriptions
- Score and rank candidate skills per sub-task
Layer 3 — Composition (Graph Generation)
Resolve dependencies and generate an execution graph:
- Analyze data flow between matched skills (output → input compatibility)
- Determine execution order: parallel where independent, sequential where dependent
- Generate a StateGraph definition with proper edges and state management
Decision Framework
When composing skills, follow this decision tree:
User Query
│
├─ Single skill sufficient?
│ └─ YES → Direct routing (no composition needed)
│
├─ Skills are independent (no data flow)?
│ └─ YES → Parallel execution graph
│
├─ Skills have linear dependency?
│ └─ YES → Sequential pipeline
│
└─ Skills have complex dependencies?
└─ YES → Mixed DAG with fan-out/fan-in
Mandatory Output Format
Every composition result MUST follow this structure:
## Composition Report
### Discovered Skills
| Rank | Skill | Match Score | Role in Workflow |
|------|-------|-------------|------------------|
| 1 | skill-a | 0.92 | Primary analysis |
| 2 | skill-b | 0.85 | Secondary validation |
### Dependency Analysis
+-- skill-a (independent, can start immediately)
| ↓ output: analysis_result
+-- skill-b (depends on skill-a output)
| ↓ output: validation_result
+-- aggregator (fan-in from all skills)
### Generated StateGraph
- **Nodes**: [list of skill nodes + utility nodes]
- **Edges**: [list of directed edges with conditions]
- **Execution Mode**: [parallel | sequential | mixed]
- **Estimated Steps**: N
### Composition Confidence
- **Coverage**: [0.0 - 1.0] — how well skills cover the intent
- **Compatibility**: [0.0 - 1.0] — how well skill I/O contracts align
- **Recommendation**: [COMPOSE | PARTIAL_COMPOSE | MANUAL_REVIEW]
Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|---|
| Over-composition | Too many skills, high latency | Limit to essential skills, prefer fewer |
| Forced sequencing | Independent skills run serially | Detect independence, parallelize |
| Ignoring I/O contracts | Skill outputs don't match next inputs | Validate data flow compatibility |
| Blind matching | Match by name only | Use semantic + metadata + tag matching |
| Monolithic workflow | One giant graph | Decompose into sub-graphs where possible |
Composition Strategies
| Strategy | When to Use | Execution Pattern |
|---|
| Pipeline | Linear data transformation | A → B → C |
| Fan-out/Fan-in | Independent analyses | A → [B, C, D] → Aggregate |
| Conditional | Domain-dependent routing | A → if(X) B else C |
| Iterative | Refinement loops | A → B → check → (loop or exit) |
Available Scripts
| Script | Purpose | Timeout |
|---|
_llm_client | Shared LLM client (SpoonOS LLMManager + HTTP fallback) | — |
skill_discovery | Parse SKILL.md metadata + semantic intent matching | 60s |
workflow_composer | Generate StateGraph workflow from matched skills | 30s |
Full I/O specs: see references/script-api.md
Context Variables
{{query}}: User intent or task description{{skill_registry_path}}: Path to scan for skills{{max_skills}}: Maximum skills to compose{{execution_mode}}: auto, sequential, parallel, mixed{{provider}}: LLM provider for semantic matching
Reasoning Trace Template
For complex composition tasks, output a structured reasoning trace:
### Reasoning Trace
**Entry Point**: [signal type] → [entry layer] → [initial skill]
**Forward Trace ↓** (Intent → Sub-tasks → Skills):
+-- User Intent: "{query}"
| ↓ decompose
+-- Sub-task 1: [description] → Skill: [name] (score: X.XX)
| ↓ data-flow
+-- Sub-task 2: [description] → Skill: [name] (score: X.XX)
| ↓ aggregate
+-- Final Output: [StateGraph definition]
**Backward Trace ↑** (Verify composition correctness):
+-- Output contract: Does the graph produce the expected result?
| ↑
+-- Dependency check: Are all data-flow edges valid?
| ↑
+-- Coverage check: Does the skill set cover the full intent?
**Attempt Log**:
| # | Method | Result | Learning |
|---|--------|--------|----------|
| 1 | [approach] | [outcome] | [insight] |
Metacognition Layer
Before finalizing any composition, perform these self-checks:
Pre-Composition Checks
- Intent completeness: Does the query decomposition cover all aspects?
- Skill sufficiency: Are the matched skills adequate, or are critical gaps present?
- Over-composition risk: Am I composing more skills than necessary?
Post-Composition Checks
- Graph validity: Is the StateGraph a valid DAG (no cycles, proper entry/exit)?
- Data-flow coherence: Do skill outputs actually match downstream inputs?
- Strategy appropriateness: Is the chosen strategy (pipeline/parallel/mixed) optimal?
- Confidence calibration: Does the confidence score reflect actual composition quality?
Reflection Prompt
"I have composed {{skill_count}} skills into a {{strategy}} workflow.
Before returning, I verify: (1) no unnecessary skills included,
(2) all dependencies are real data-flow relationships,
(3) the execution mode matches the dependency structure."
Tool Priority (PREFER Directives)
- PREFER
skill_discovery script over manual SKILL.md parsing for skill matching
- PREFER
workflow_composer script over hand-crafted StateGraph definitions
- PREFER SpoonOS LLMManager over direct HTTP API calls for LLM interactions
- PREFER tag-based heuristic matching as first pass before LLM semantic matching
- PREFER immutable dataclass patterns over mutable dict manipulation
- PREFER stdin/stdout JSON protocol over file-based I/O for script communication
Pressure Scenarios (Skills TDD)
See references/pressure-scenarios.md for 5 structured test scenarios covering:
- Multi-domain pipeline detection
- Independent parallel analysis
- Single skill (no composition)
- Graceful empty results
- LLM-unavailable degradation
Documentation Completeness Check
Before responding, verify this skill's documentation covers:
If any item is missing, flag it in the response before proceeding.
