---
name: skill-cauldron
description: "You MUST use this when the user wants to merge, combine, fuse, or blend multiple skills/prompts into a single more powerful skill. This is the 'alchemy furnace' for skill composition — it takes 2 or more skills as input and produces a refined, unified skill that achieves 1+1>2 through structured intelligent merging. Trigger keywords: 'merge skills', 'combine skills', 'fuse skills', '炼妖壶', '融合SKILL', '合并skill', 'skill合并', '炼妖', '合成skill'. Use this even when the user hints at combining ('can these two work together?', 'I wish X had Y'). DO NOT USE for: installing skills, version management, file concatenation, or skill evaluation (use darwin-skill)."
license: MIT
version: "1.2.0"
compatibility: "Claude Code, OpenCode, Trae, Codex CLI, Cursor, Gemini CLI — agent-skills-lint: 0 errors"
---
# Skill Cauldron (炼妖壶) v1.2

**Meta-skill**: consumes skills, produces a new fused skill. Does NOT install, evaluate, or catalog.

## Quick Reference

| Property | Value |
|----------|-------|
| Best for | 2 complementary skills → 1 super-skill |
| Input | 2+ skill directories |
| Output | 1 merged SKILL.md + bundled resources |
| Side effects | Creates new directory; never modifies inputs |
| Avg. time | 5-10 min (human confirms at Round 3) |

## When NOT to Use

- Replacing one skill with a better version → use the better one
- Two skills that do the same thing → pick the best
- Installing skills → use your runtime's install command
- Evaluating quality → use `darwin-skill`
- Simple concatenation → use `cat`, not the Cauldron

The Skill Cauldron is an alchemy furnace for merging multiple skills into a single, more powerful skill.

## Core Philosophy

- **Structured Fusion**: Not simple concatenation, but intelligent component-level merging
- **Controllable**: Every step is transparent, with user confirmation at key decision points
- **Base-Dominant**: The strongest skill serves as the foundation; others enrich it
- **Conflict Resolution**: Identifies and resolves contradictions between skills
- **1+1>2**: The merged skill must be genuinely more capable than any individual input
- **Full Fidelity**: Scripts, assets, configs, and references must be preserved and properly merged

## When to Use

- Merging 2+ skills that complement each other
- Creating a composite skill from related capabilities
- Evolving an existing skill by fusing it with new abilities
- Building a "super-skill" that covers multiple domains

## Supported Input Formats

| Format | Priority | Notes |
|--------|----------|-------|
| TRAE SKILL.md | P0 | Standard format with YAML frontmatter + Markdown |
| Generic Markdown Prompt | P1 | Plain markdown prompt files |
| YAML/JSON Prompt | P2 | Structured prompt definitions |

## The Five-Round Refinement Process

```
Round 1: PARSE    → Extract structural components from each skill
Round 2: COMPARE  → Evaluate quality, identify overlaps/conflicts/complements
Round 3: CONFIRM  → Present analysis, let user adjust merge strategy
Round 4: MERGE    → Execute the fusion, producing the unified skill
Round 5: VALIDATE → Verify completeness, consistency, and quality
```

## Round 1: Parse

For each input skill, extract and catalog:

1. **Frontmatter**: name, description, tags, license
2. **Workflow**: step-by-step process, decision trees, gates
3. **Rules**: hard rules, anti-patterns, constraints, litmus checks
4. **Examples**: input/output examples, usage patterns
5. **Scripts/Tools**: executable scripts, helper utilities
6. **Assets**: images, fonts, icons, helper libraries
7. **References**: external docs, helper files
8. **Agent Config**: agents/openai.yaml if present
9. **Philosophy**: core design principles, working model

## Round 2: Compare

### Quality Assessment

Score each skill on these dimensions (1-5 scale):

| Dimension | What to Evaluate |
|-----------|-----------------|
| Structural Integrity | Clear workflow, well-organized sections |
| Rule Clarity | Constraints are explicit and verifiable |
| Example Richness | Sufficient input/output demonstrations |
| Depth/Complexity | Feature coverage and sophistication |
| Documentation Quality | Clear descriptions, no ambiguity |
| Resource Richness | Scripts, assets, references available |

Base selection criteria (in order):
1. Highest total score
2. User-specified preference
3. Most resource-complete (has scripts/assets)
4. Most recently updated
5. Largest content volume

### Overlap Detection

Identify:
- **Identical rules**: Same constraint appearing in multiple skills
- **Similar workflows**: Steps that achieve the same goal
- **Duplicate examples**: Functionally identical demonstrations
- **Shared philosophy**: Common design principles

### Conflict Detection

Flag these conflict types:

| Conflict Type | Example | Resolution Strategy |
|---------------|---------|---------------------|
| Contradictory Rules | Skill A says "No cards" but Skill B says "Use cards" | Keep base skill's rule; note alternative |
| Opposite Workflows | Skill A: explore first. Skill B: build first. | Integrate as phases: explore → build |
| Conflicting Personas | Skill A: formal. Skill B: casual. | Base persona dominates; add flexibility |
| Output Format Clash | Skill A: JSON. Skill B: Markdown. | Support both or context-dependent format |

### Complement Mapping

Identify unique strengths of each skill that should be preserved.

### 🆕 Pre-Merge Compatibility Screen

> From experimental data in `references/lessons-from-experiments.md`. Run BEFORE committing to full Round 3-5 merge.

**Fusion type classification:**

| Type | Characteristic | Success Rate | Action |
|------|---------------|:--:|------|
| **Complementary** | A and B do different things; together form a complete chain | Highest | Proceed to Round 3 |
| **Enhancing** | A does main work; B provides unique methodology | High | Proceed to Round 3 |
| **Substitutive** | A and B do the same thing; different methods only | Low | ⚠️ Pick the best one; do not merge |
| **Orthogonal** 🆕 | A and B operate in different domains; no chain possible | Zero | 🛑 Keep separate; no integration point exists |

**Quick compatibility score** (score ≥6 → high probability of 1+1>2):

| Signal | +pts | -pts |
|--------|------|------|
| Different but chainable workflows | +3 | — |
| Complementary output formats | +2 | Formats fundamentally incompatible |
| Shared design philosophy | +2 | Core philosophy contradiction |
| Rules have no conflicts | +1 | 3+ rule conflicts |
| Both have scripts/assets | +1 | Asset count >50 (too heavy) |
| Both are pure prompts | +1 | One extremely complex, other trivial |
| 🆕 Combined agent count >8 | — | -2 | Complexity explosion risk |
| 🆕 Agent architecture mismatch | — | -1 | Hierarchical vs Pipeline vs Direct incompatible |

**If score < 6 → ⚠️ warn user: "Low compatibility. Strongly consider keeping as separate skills."**

**Five-level conflict severity** (from experimental data):

| Level | Description | Action |
|-------|------------|--------|
| L1 Minor | Format inconsistency (naming style) | Auto-fix |
| L2 Moderate | Workflow order conflict | Resolve by phasing |
| L3 Serious | Rule contradiction (A says do X; B says don't do X) | Context-based routing |
| L4 Fatal | Output format incompatible | Dual-mode or bridge layer |
| L5 Unmergeable | Core philosophy opposition | 🛑 Abandon merge; keep as two independent skills |

**If L5 detected → 🛑 STOP. Do not proceed to Round 3. Report to user: "These skills have fundamentally incompatible philosophies. Merging them would produce a broken skill. Recommend keeping separate."**

### 🆕 Selective Merge: Handling Mixed-Type Scenarios

> When multiple skills are involved (3+), different pairs may have different fusion types. Do NOT force an all-or-nothing decision.

**Step 1: Pairwise classification** — classify every pair:

| Pair | Type | Score | Action |
|------|------|:--:|------|
| A ↔ B | Complementary | 8 | ✅ Merge |
| A ↔ C | Substitutive | 4 | ⚠️ Don't merge; extract shared layer |
| B ↔ C | Orthogonal | 1 | 🛑 Keep separate |

**Step 2: Identify mergeable subset** — only pairs with score ≥6 AND non-Substitutive/non-Orthogonal type.

**Step 3: Extract shared infrastructure** — if Substitutive pairs exist, extract the common capability as a standalone shared layer (referenced by both, not merged into either). Example: Agnes生图生视频 is the shared API layer; AI视频制作 and 小说转漫画 consume it — do NOT merge the consumer with its dependency.

**Step 4: Present the architecture decision**:

```
Merge:        A + B → AB (complementary super-skill)
Keep:         C (independent, referenced by AB)
Extract:      Shared layer S (used by AB and C)
```

**Key rule**: Substitutive pair → don't merge, extract shared layer. Orthogonal pair → keep separate. Only Complementary/Enhancing pairs proceed to Round 3 full merge.

## Round 3: Confirm 🔴 CHECKPOINT

> 🛑 **STOP: Human approval required before proceeding to merge.**

Present to the user:
- Quality scores
- Recommended base
- Component inventory
- Overlaps and conflicts
- Proposed merge strategy
- Merged skill preview

User can approve, change base, modify resolutions, add/remove components, or rename.

## Round 4: Merge

Execute the fusion following these component-level rules:

### Frontmatter Fusion

| Field | Merge Rule |
|-------|-----------|
| name | User-specified or auto-generated |
| description | Combine descriptions highlighting unified capability |
| tags | Union of all tags, deduplicated |
| license | Most restrictive wins, or list all |

### Workflow Integration

1. Start with base skill's workflow as skeleton
2. Identify insertion points for other skills' unique steps
3. When workflows conflict, create unified flow:
   - Sequential: A's steps → B's steps → C's steps
   - Phase-based: Exploration → Creation → Refinement
   - Conditional: "If X, follow A; if Y, follow B"
4. Add transition logic between integrated sections

### Rules Consolidation

1. Collect all rules from all skills
2. Remove exact duplicates
3. Resolve conflicts (per Round 3 decisions)
4. Reorganize by category
5. Add cross-references where rules interact

### Examples Aggregation

1. Keep all unique examples
2. Remove functionally identical examples
3. Add composite examples showing merged skill in action
4. Label examples by origin skill when helpful

### Scripts & Tools Merge

1. Create `scripts/` directory in output
2. Copy ALL scripts from base skill
3. Copy scripts from other skills, renaming if conflicts:
   - `script.py` → `{skill-name}_{original-filename}`
4. Update all script references in SKILL.md
5. Merge dependency files (requirements.txt, package.json):
   - Union of all dependencies
   - Resolve version conflicts

### Assets Merge

1. Create `assets/` directory in output
2. Copy ALL assets from base skill
3. Copy assets from other skills, renaming if conflicts
4. Preserve subdirectory structure
5. Update all asset references in SKILL.md

### References Merge

1. Create `references/` directory in output
2. Copy ALL reference docs from base skill
3. Copy reference docs from other skills, renaming if conflicts
4. Update all reference links in SKILL.md

### Agent Config Handling

1. Check if any input skill has `agents/openai.yaml`
2. If only one has it: copy to output
3. If multiple have it: merge display_name and short_description
4. If none has it: skip

### Philosophy Synthesis

1. Extract core principles from each skill
2. Identify shared principles (reinforce)
3. Identify complementary principles (integrate)
4. Identify conflicting principles (resolve per Round 3)
5. Write unified "Core Philosophy" section

## Round 5: Validate

### Completeness Check

- [ ] Frontmatter has all required fields
- [ ] Workflow is clear and actionable
- [ ] Rules are explicit and verifiable
- [ ] At least one example is provided
- [ ] All script references point to existing files
- [ ] All asset references point to existing files
- [ ] All reference links point to existing files
- [ ] Agent config is valid (if present)

### Consistency Check

- [ ] No contradictory rules remain
- [ ] Workflow steps reference existing rules
- [ ] Examples align with stated rules
- [ ] Philosophy matches actual workflow
- [ ] Script names in SKILL.md match actual filenames

### Quality Check

- [ ] Merged skill is more capable than any individual input
- [ ] No unnecessary complexity added
- [ ] Clear value proposition in description
- [ ] Would be useful to a user who hasn't seen the original skills
- [ ] All original capabilities are preserved

### 🆕 1+1>2 Validation (from `references/lessons-from-experiments.md`)

> 🔴 **CHECKPOINT: All 4 questions must be answered before merge is considered complete.**

| # | Question | Pass Condition |
|---|----------|---------------|
| 1 | Can the merged product do something neither original could do alone? | Yes → continue |
| 2 | Is the merged product faster/better/stronger than using A+B separately? | Yes → continue |
| 3 | Did the merge produce a NEW capability (neither A nor B had)? | Yes → true 1+1>2 |
| 4 | 6 months later, will users thank you for it being one SKILL, or break it apart? | Thank → success |

**Quantitative targets:**

| Metric | Target |
|--------|:--:|
| Workflow step reduction | ≥30% |
| User's SKILL load reduced by | -1 |
| Lost functionality | 0 |
| New functionality (not in originals) | ≥1 |
| File size increase | ≤150% of sum of originals |

If any check fails, return to Round 4 with specific fixes needed.

### Format Check

- [ ] Valid YAML frontmatter
- [ ] Proper Markdown structure
- [ ] All internal links/references valid
- [ ] Scripts are executable (if applicable)

If any check fails, return to Round 4 with specific fixes needed.

## Auto-Generated Merge Report

After Round 5 passes, automatically generate `MERGE-REPORT.md` in the output directory with:
- Input skill profiles
- Merge decisions log
- Components merged table
- Output summary
- Known issues
- Recommendations

## Output Structure

```
{output-path}/
├── SKILL.md              # Merged skill definition
├── MERGE-REPORT.md       # Auto-generated merge log
├── scripts/              # Merged and renamed scripts
├── assets/               # Merged assets
├── references/           # Merged reference docs
├── agents/               # Merged agent config (if any)
│   └── openai.yaml
└── LICENSE.txt           # License information
```

## Version & Lineage Tracking

In the merged SKILL.md, add a Lineage section:

```markdown
## Lineage

- **Parents**: [skill-a-name], [skill-b-name]
- **Base**: [base-skill-name]
- **Cauldron Version**: v1.2
- **Merged**: [timestamp]
- **Merge Operator**: [AI/user identifier]
```

## Usage Example

**User Request:**
> "Use the Skill Cauldron to merge brainstorming and frontend-skill. Save to /workspace/skills/creative-frontend/"

**Execution Flow:**

1. **Parse**: Extract components from both skills
2. **Compare**: Evaluate quality, identify base, find conflicts
3. **Confirm**: Present analysis, user approves
4. **Merge**: Execute fusion following component-level rules
5. **Validate**: All checks pass
6. **Output**: Save merged skill
7. **Report**: Auto-generate MERGE-REPORT.md

### Rejected Merge Example

**User Request:**
> "「大神大脑」和「second-brain」能融合吗？分析兼容性"

**Execution Flow:**

1. **Parse**: Extract components.
   - 大神大脑: 创作大脑·文风引擎·18创作脑·向外创造
   - second-brain: 知识管理·CODE+PARA+Zettelkasten+GTD·向内整理

2. **Compare — Pre-Merge Compatibility Screen**:
   - Fusion type: **Orthogonal** — operate in different domains; no chain possible
   - Quick score: +0(not chainable) +0(outputs incompatible) +0(philosophy clash: constraint vs expansion) = **1 < 6 → ⚠️ Strong warning**
   - Conflict: **L5 Unmergeable** — core philosophy opposition. 大神大脑 constrains possibilities (style inertia); second-brain expands connections (knowledge network). These are philosophically incompatible.

3. **🛑 STOP. Do not enter Round 3.** Report to user:
   > "These skills have fundamentally incompatible philosophies. Merging them would produce a broken skill — one that simultaneously demands you 'write in 天下霸唱's voice' and 'apply CODE methodology to organize your notes.' Recommend keeping separate.
   >
   > **Better alternative**: They can collaborate without merging — second-brain manages creative source material → 大神大脑 applies style constraints during writing. Two SKILLs, one creative pipeline."

4. **No Round 4-5.** Merge aborted at compatibility screen.

## Key Principles

> Foundational principles: see [Core Philosophy](#core-philosophy) above. The following are operational corollaries derived from experimental practice.

- **Never lose a unique capability**: Preserve special abilities from every input skill
- **Conflicts are opportunities**: Contradictions reveal deeper synthesis possibilities
- **Quality over quantity**: Better to merge 2 skills well than 5 poorly
- **Documentation over automation**: Establish merge report standards before building tooling (from `references/lessons-from-experiments.md`)

## Anti-Patterns

- **Frankenstein Merge**: Simply concatenating without integration
- **Rule Bloat**: Keeping contradictory rules side-by-side
- **Base Neglect**: Ignoring base skill's strengths
- **Over-Merging**: Combining too many skills, unusable complexity
- **Silent Conflicts**: Letting contradictions remain unflagged
- **Resource Loss**: Dropping scripts, assets, or configs during merge

## Failure Recovery

> 🆕 From experimental data (see `references/lessons-from-experiments.md`): the 3 most common fatal failures and their prevention.

| Failure Scenario | Detection | Prevention | Recovery |
|-----------------|-----------|------------|----------|
| **Script/Asset Loss** (80% incidence in v1.0) | Round 5 completeness check fails | Round 1: list all file paths explicitly. Round 5: verify count matches | Return to Round 4; re-copy all files using the checklist |
| **Silent Conflicts** (60% incidence) | Round 5 consistency check finds contradictions | Round 2: use the 4-type conflict detection table. Mark L3+ conflicts for user review | Return to Round 3; present unresolved conflicts to user for decision |
| **Wrong Base Selected** (30% incidence) | Merged skill underperforms vs. expected | Use 6-dim quality scoring (Round 2) + compatibility screen. If scores tie, let user pick | Return to Round 2; swap base and re-merge |
| **Parse fails** (SKILL.md unreadable) | Round 1 cannot extract components | Verify file path; check encoding | 🛑 Skip this skill; note in merge report |
| **User rejects merge in Round 3** | User says no or requests major changes | — | Return to Round 2; adjust base/compatibility/resolution per user feedback |
| **Merge report generation fails** | MERGE-REPORT.md not created | Ensure output directory is writable | Generate inline in conversation as fallback |
| **Merged skill exceeds size limit** | Output >150% of sum of inputs | Monitor file size during Round 4 | 🛑 STOP; ask user: "proceed with oversized output / trim / abandon" |

### See Also

- `references/lessons-from-experiments.md` — Experimental knowledge cards: fusion type taxonomy, failure incidence rates, 4-question 1+1>2 test, v1.0→v1.1 improvement roadmap

## 🆕 When Merge is Rejected: Constructive Alternatives

> A rejected merge is not a dead end. When L5 triggers or score < 6, offer at least one constructive alternative.

| Scenario | Don't Just Say "No" | Offer |
|------|------|------|
| **Orthogonal type** | "Can't merge" | "They can collaborate without merging: SKILL A produces output → SKILL B consumes it. Two SKILLs, one pipeline." |
| **Substitutive type** | "Pick the best one" | "Extract shared methodology into a cross-SKILL reference file. Both SKILLs can reference it without merging." |
| **L5 philosophy clash** | "Incompatible" | "Keep independent but coordinate via orchestrator routing: use trigger words to dispatch to the right SKILL based on user intent." |
| **Agent count >8** | "Too complex" | "Consider a facade SKILL that routes to specialized sub-SKILLs, rather than merging all agents into one monolith." |
| **Score <6 but >3** | "Low compatibility" | "The low-scoring dimensions are: [list]. If these can be resolved, re-score. Otherwise, keep separate." |

**Principle**: The Cauldron's job is not just to say "yes" or "no" to merging — it's to find the optimal architecture for a set of capabilities, whether that's one merged SKILL, a layered architecture, or coordinated independent SKILLs.