Skill chain generator

Skill Chain Generator

Create declarative multi-skill workflows using YAML definitions. Automatically generates production-ready SKILL.md files with state machines, routing logic, and best practices inspired by /comet and /plan.

Core Concept

What is a Skill Chain? A skill chain is a coordinated multi-skill workflow where one master skill routes through multiple sub-skills based on state, user decisions, and workflow progress. Examples: /comet (open → design → build → verify → archive), /plan (planning with files pattern).

Why Declarative? Instead of manually writing hundreds of lines of routing/state logic, define your chain in YAML and let this generator produce the complete SKILL.md template.

Comet Compatibility: This generator supports full Comet-style chains: .comet.yaml state fields (phase/build_mode/tdd_mode/review_mode/verify_mode/isolation/verify_failures), preset escalation (hotfix→tweak→full), Node Contracts (Skill Binding / Required Skill Call / Output Schema / Guardrail / Handoff), subagent dispatch contract (DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT), and workflow kind distinction (comet-five-phase-overlay vs workflow-kernel).

---

Comet Compatibility Mode

When generating chains for Comet-style workflows, use these extended fields:

Extended State Fields

states:
  - id: build
    name: "实施构建"
    skill: "openspec-apply-change"
    model: opus                    # Per-state model override
    build_mode: subagent-driven-development  # subagent-driven-development | executing-plans | direct
    tdd_mode: tdd                  # tdd | direct
    review_mode: standard          # off | standard | thorough
    isolation: branch              # current | branch | worktree

Preset Escalation

preset_escalation:
  - from: hotfix
    to: full
    signal: "scope_expansion_detected"
  - from: tweak
    to: full
    signal: "complexity_exceeds_tweak"

Node Contract

nodes:
  execute:
    required_skill_calls:
      - skill: "openspec-apply-change"
        reason: "Implement tasks from change"
    output_schema:
      - "tests pass"
      - "commits made"
    guardrail: "block if tests fail"
    handoff: "implemented_files + test_results"

Subagent Dispatch Contract

Generated skills must define agent return states: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT. Risk signals (cross-module changes, auth, concurrency, schema migration, public API) must be checked and reported by implementer agents.

Workflow Kind

chain:
  kind: comet-five-phase-overlay  # preserves .comet.yaml state | workflow-kernel for custom

---

Quick Start

1. Discover Existing Skills (Avoid Reinventing)

Before defining your chain, check what's already available:

# Query installed skills
bash ~/.claude/skills/skill-chain-generator/scripts/discover.js --local

# Search for mature solutions online (optional)
bash ~/.claude/skills/skill-chain-generator/scripts/discover.js --web "workflow automation skill chain"

The discover script will:

• List all installed skills with their descriptions
• Match your needed functionality (e.g., "brainstorming", "code-review")
• Suggest reuse instead of creating new skills
• Provide installation commands for missing skills

Best Practice: Always discover first → reuse existing → only create new when necessary.

2. Define Your Chain

Create a chain.yaml:

chain:
  name: "feature-workflow"
  description: "Add new feature workflow"
  model: "z.ai/glm-5.2"
  
  states:
    - id: explore
      name: "探索需求"
      skill: "research-assistant"  # ← Use discovered skill name
      next: design
      
    - id: design
      name: "设计方案"
      skill: "superpowers:brainstorming"
      next: build
      decision_point:
        question: "设计方案是否可行？"
        options: ["继续", "重新设计"]
        
    - id: build
      name: "实施构建"
      skill: "superpowers:writing-plans"
      next: verify
      
    - id: verify
      name: "验证测试"
      skill: "code-reviewer"
      next: [archive, build]  # 条件分支
      conditions:
        - if: "review_result == 'pass'"
          then: archive
        - if: "review_result == 'fail'"
          then: build
          
    - id: archive
      name: "归档"
      skill: "comet-archive"
      end: true

Tip: Use skill names from discover.js output. Format: skill-name or group:skill.

3. Generate SKILL.md (with Reuse Analysis)

bash ~/.claude/skills/skill-chain-generator/scripts/generate.js chain.yaml --check-reuse

The --check-reuse flag will:

• Verify each referenced skill exists locally
• Suggest alternatives if a skill is missing
• Generate a reuse report (reuse_report.json) showing:
  • installed_skills: Already available
  • missing_skills: Need to create or find
  • suggested_alternatives: Closest matches from local skills
  • reuse_rate: Percentage of skills you can reuse

4. Find Missing Skills Online (Optional)

If you have missing skills, use --online-search to get search suggestions:

bash ~/.claude/skills/skill-chain-generator/scripts/generate.js chain.yaml --check-reuse --online-search

This will print commands like:

/skill-find "brainstorming agent skill github"

Run those commands to search GitHub for public skills. Install any that match your needs.

5. Create Only What's Missing

Use /skill-creator only for skills that cannot be found online. For skills with good online candidates, review, install, and adapt instead of building from scratch.

---

Tool Reference

discover.js

Skill discovery utility.

# List all locally installed skills
bash ~/.claude/skills/skill-chain-generator/scripts/discover.js --local

# Output as JSON (for scripts)
bash ~/.claude/skills/skill-chain-generator/scripts/discover.js --local --format json

generate.js

Chain generation utility.

# Basic generation
bash generate.js chain.yaml [output-dir]

# With reuse check
bash generate.js chain.yaml . --check-reuse

# With online search suggestions
bash generate.js chain.yaml . --check-reuse --online-search

---

YAML Schema Reference

Top-Level Fields

Field	Type	Required	Description
chain.name	string	✅	Skill chain identifier (kebab-case)
chain.description	string	✅	Frontmatter description
chain.model	string	❌	Default model (inherit if omitted)
chain.states	array	✅	State definitions
chain.preset_detection	array	❌	Preset routing logic
chain.decision_points	array	❌	Global decision points
chain.reuse_check	bool	❌	Enable skill existence check (default: true)
chain.kind	string	❌	comet-five-phase-overlay (preserves .comet.yaml) or workflow-kernel (custom)

State Definition

states:
  - id: open                # Unique state ID
    name: "开启"            # Human-readable name
    skill: "comet-open"     # Skill to invoke (format: "skill-name" or "group:skill")
    next: design            # Next state ID (single)
    # OR conditional branching:
    next:                  # Conditional next states
      - condition: "verify_result == 'pass'"
        state: archive
      - condition: "verify_result == 'fail'"
        state: build
    decision_point:         # Optional user decision at this state
      question: "继续吗？"
      options: ["是", "否"]
    end: false             # Mark as terminal state (default: false)
    model: opus            # Per-state model override (optional)
    build_mode: subagent-driven-development  # subagent-driven-development | executing-plans | direct
    tdd_mode: tdd          # tdd | direct
    review_mode: standard  # off | standard | thorough
    isolation: branch      # current | branch | worktree

Preset Detection

preset_detection:
  - if: "user_intent == 'hotfix' && file_count < 3"
    then: "hotfix-chain"      # Use a different chain variant
  - if: "user_intent == 'tweak' && file_count < 5"
    then: "tweak-chain"

Presets allow you to define shortcut workflows (like comet-hotfix / comet-tweak).

Preset Escalation

Define conditions where a preset should upgrade to a more comprehensive workflow:

preset_escalation:
  - from: hotfix
    to: full
    signal: scope_expansion_detected
    condition: "file_count > 3 || cross_module_change"
  - from: tweak
    to: full
    signal: complexity_exceeds_tweak
    condition: "design_doc_required || schema_change"

Use comet state transition <name> preset-escalate to execute escalation after user confirmation.

Decision Points

Two ways to define decisions:

1. Inline (per-state):

- id: design
  decision_point:
    question: "设计方案是否满意？"
    options: ["满意，继续", "需要修改"]

2. Global:

decision_points:
  - at: verify
    question: "验证结果如何？"
    options: ["通过", "失败"]

Skill Reuse & Discovery

Set chain.reuse_check: true (default) to enable automatic skill discovery:

chain:
  name: "my-workflow"
  reuse_check: true  # Check for existing skills before generating

The generator will:

1. Query local skill registry (~/.claude/skills/*/SKILL.md)
2. For missing skills, search known marketplaces
3. Generate a reuse report with install suggestions
4. Flag skills that need to be created from scratch

---

Generated SKILL.md Structure

The generator produces a complete SKILL.md following the Comet pattern:

---
name: <chain.name>
model: <chain.model>
description: <chain.description>
---

# <chain.name>

## 决策核心

### 状态管理
- State file: `<workflow>/<change>/.<chain>.yaml`
- Comet fields: phase, build_mode, tdd_mode, review_mode, isolation, verify_mode, verify_failures, verify_result, workflow, language, base_ref, design_doc, plan

### 阶段自动检测
<generated routing logic>

### 预设检测 (Optional)
<generated preset detection>
- `comet state transition <name> preset-escalate` for preset upgrades

### 决策点 (Optional)
<generated decision point handlers>

### 子代理派发契约
Implementer agent return states: `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`
Risk signals: cross-module, auth, concurrency, schema migration, public API change

### 节点合约 (Node Contract)
Each node declares: Skill Binding, Required Skill Call, Output Schema, Guardrail, Handoff

### 错误处理速查
<generated error handling table>

### 阶段衔接
<generated transition rules>
- Exit gate: must pass 36+2 quality standards before transition

## 子命令速查
| 阶段 | 技能 | 说明 |
|------|------|------|

## 参考附录
- 文件结构
- 最佳实践
- 验证与归档

---

## Scripts

Auto-generated helper scripts:
- `scripts/<chain>-state.js` - State transitions
- `scripts/<chain>-guard.js` - Phase verification
- `scripts/<chain>-handoff.js` - Context handoff

---

Advanced Patterns

Conditional Branching

Use conditions for multi-way transitions:

- id: verify
  conditions:
    - if: "tests_pass && lint_clean"
      then: archive
    - if: "tests_pass && !lint_clean"
      then: fix-lint
    - if: "!tests_pass"
      then: debug

Preset Variants

Define multiple chain variants for different scenarios:

chain:
  name: "deploy-workflow"
  # ... states (full workflow)
  
presets:
  hotfix:
    skip_states: [design]
    conditions: "file_count < 3 && bug_fix"
  emergency:
    skip_states: [design, verify]
    conditions: "production_down"

Model Selection per State

Override model for specific states:

states:
  - id: brainstorm
    skill: "superpowers:brainstorming"
    model: "z.ai/glm-5.2"  # Force advanced model for design
    next: plan

---

Examples

See examples/ directory for complete working templates:

• simple-linear.yaml - Basic 5-state linear workflow
• comet-lite.yaml - Simplified Comet pattern
• preset-workflow.yaml - With hotfix/tweak variants
• conditional-workflow.yaml - Complex branching logic

---

Best Practices

1. Keep chains focused - 5-7 states maximum per chain
2. Use descriptive state IDs - design-doc-approved not just design
3. Mark terminal states - Set end: true for archive/completion
4. Document decision points - Explain why users need to decide
5. Include error handling - Define what happens on failure
6. Test each path - Ensure all conditional branches reachable
7. Leverage presets - Define hotfix/tweak variants for speed
8. Inherit model - Set model at chain level, avoid per-state overrides

---

Integration with Other Skills

Skill-creator: Create individual sub-skills first, then reference them in your chain.

Plan: Use /plan to design the chain structure before writing YAML.

Comet: Analyze existing /comet chains by reading its SKILL.md and templates.

Skill-fix: If a chain skill has defects (missing state fields, incorrect routing, preset misconfiguration), call /skill-fix to diagnose and repair.

---

Troubleshooting

Issue	Solution
"Skill not found" error	Check skill name format: use "skill-name" or "group:skill"
Circular dependency	Ensure no state loops back to itself without exit
Missing decision point	Decision points require AskUserQuestion in generated code
Preset not triggering	Check condition syntax - must be valid Python expression

---

Implementation Details

Frontmatter:

• name: from chain.name
• model: from chain.model (or omit to use default)
• description: from chain.description

Code Generation:

• Uses Jinja2 templates in templates/
• Main template: skill.md.j2
• Helper templates: state-router.j2, decision-points.j2, guard.j2

Validation:

• YAML syntax check
• State ID uniqueness
• Skill existence verification (optional)
• Circular dependency detection

---

Future Enhancements

• Visual chain editor (web UI)
• JSON Schema validation for YAML
• Automatic dependency graph generation
• Cost estimation based on skill invocations
• Multi-chain composition (chain-of-chains)
• Export to PlantUML / Graphviz

---

Inspired by: Comet (OpenSpec + Superpowers), Plan (Manus pattern)
Pattern: State Machine + Skill Routing
Target: Complex, multi-phase, collaborative development workflows