gh-cskiro-claudex-meta-tools/skills/skill-creator/examples/complex-skill/README.md

Complex Skill Structure Example

This example shows the structure for skills with multiple operating modes or data processing capabilities.

Directory Structure

Mode-Based Complex Skill

complex-skill/
├── SKILL.md           # Agent manifest with mode detection (required)
├── README.md          # User documentation (required)
├── plugin.json        # Marketplace metadata (required)
├── CHANGELOG.md       # Version history (required)
├── modes/             # Mode-specific workflows (required for mode-based)
│   ├── mode1-name.md
│   ├── mode2-name.md
│   └── mode3-name.md
├── data/              # Reference materials (optional)
│   ├── best-practices.md
│   └── troubleshooting.md
├── examples/          # Sample outputs per mode (optional)
│   ├── mode1-example.md
│   └── mode2-example.md
└── templates/         # Reusable templates (optional)
    └── output-template.md

Data Processing Complex Skill

complex-skill/
├── SKILL.md           # Agent manifest (required)
├── README.md          # User documentation (required)
├── plugin.json        # Marketplace metadata (required)
├── CHANGELOG.md       # Version history (required)
├── scripts/           # Processing scripts (required for data processing)
│   ├── processor.py
│   ├── indexer.py
│   ├── query.py
│   └── generator.py
├── data/              # Reference materials (optional)
│   └── config-defaults.yaml
├── examples/          # Sample outputs (optional)
│   └── sample-report.md
└── templates/         # Report templates (optional)
    └── report-template.md.j2

When to Use Complex Structure

Use this structure when:

Mode-Based:

• Multiple distinct operating modes based on user intent
• Each mode has its own workflow
• Different outputs per mode
• Clear mode detection logic needed
• Example: git-worktree-setup (single/batch/cleanup/list modes)

Data Processing:

• Processes data from files or APIs
• Performs analysis or transformation
• Generates insights or reports
• Needs helper scripts for processing
• Example: cc-insights (conversation analysis)

Characteristics

• Complexity: High
• Files: 4 required + 4+ optional directories
• Pattern: Mode-based or data-processing
• Modes: Multiple distinct modes OR data pipeline
• Scripts: Often needed for data processing
• Dependencies: May have Python/Node dependencies

SKILL.md Template (Mode-Based)

---
name: skill-name
version: 0.1.0
description: Multi-mode skill that handles X, Y, and Z
author: Your Name
---

# Skill Name

## Overview

This skill operates in multiple modes based on user intent.

## When to Use This Skill

**Trigger Phrases:**
- "mode 1 trigger"
- "mode 2 trigger"
- "mode 3 trigger"

**Use Cases:**
- Mode 1: Use case
- Mode 2: Use case
- Mode 3: Use case

## Quick Decision Matrix

\`\`\`
User Request              → Mode      → Action
─────────────────────────────────────────────────
"trigger 1"               → Mode 1    → Action 1
"trigger 2"               → Mode 2    → Action 2
"trigger 3"               → Mode 3    → Action 3
\`\`\`

## Mode Detection Logic

\`\`\`javascript
// Mode 1: Description
if (userMentions("keyword1")) {
  return "mode1-name";
}

// Mode 2: Description
if (userMentions("keyword2")) {
  return "mode2-name";
}

// Mode 3: Description
if (userMentions("keyword3")) {
  return "mode3-name";
}

// Ambiguous - ask user
return askForClarification();
\`\`\`

## Core Responsibilities

### Shared Prerequisites
- ✓ Prerequisite 1 (all modes)
- ✓ Prerequisite 2 (all modes)

### Mode-Specific Workflows
See detailed workflows in:
- \`modes/mode1-name.md\` - Mode 1 complete workflow
- \`modes/mode2-name.md\` - Mode 2 complete workflow
- \`modes/mode3-name.md\` - Mode 3 complete workflow

## Success Criteria

Varies by mode - see individual mode documentation.

SKILL.md Template (Data Processing)

---
name: skill-name
version: 0.1.0
description: Processes X data to generate Y insights
author: Your Name
---

# Skill Name

## Overview

Automatically processes data from [source] to provide [capabilities].

## When to Use This Skill

**Trigger Phrases:**
- "search for X"
- "generate Y report"
- "analyze Z data"

**Use Cases:**
- Search and find
- Generate insights
- Track patterns

## Architecture

\`\`\`
Input → Processing → Storage → Query/Analysis → Output
\`\`\`

## Workflow

### Phase 1: Data Ingestion
- Discover data sources
- Validate format
- Process incrementally

### Phase 2: Processing
- Extract features
- Generate embeddings (if semantic)
- Store in database

### Phase 3: Query/Analysis
- Search interface
- Pattern detection
- Generate reports

## Scripts

See \`scripts/\` directory:
- \`processor.py\` - Main data processing
- \`indexer.py\` - Build indexes
- \`query.py\` - Query interface
- \`generator.py\` - Report generation

## Performance

- Initial processing: [time estimate]
- Incremental updates: [time estimate]
- Search latency: [time estimate]
- Memory usage: [estimate]

Directory Purposes

modes/

For mode-based skills, each file documents one mode:

• Complete workflow for that mode
• Mode-specific prerequisites
• Mode-specific outputs
• Mode-specific error handling

scripts/

For data processing skills:

• Python/Node scripts for heavy processing
• CLI interfaces for user interaction
• Batch processors
• Report generators

Best Practices

Mode-Based Skills:

1. Clear mode boundaries: Each mode is distinct
2. Explicit detection: Unambiguous mode selection
3. Shared prerequisites: Extract common validation
4. Mode independence: Each mode works standalone
5. Detailed documentation: Each mode has its own guide

Data Processing Skills:

1. Incremental processing: Don't reprocess everything
2. State tracking: Know what's been processed
3. Progress indicators: Show progress for long operations
4. Error recovery: Handle failures gracefully
5. Performance docs: Document expected performance
6. Script documentation: Each script has clear --help

Examples of Complex Skills

Mode-Based:

• git-worktree-setup: Single/Batch/Cleanup/List modes
• Multi-format converter: Different output formats
• Environment manager: Create/Update/Delete/List

Data Processing:

• cc-insights: Conversation analysis with RAG search
• Log analyzer: Parse logs, detect patterns, generate reports
• Metrics aggregator: Collect data, analyze trends, visualize

When NOT to Use Complex Structure

Avoid over-engineering:

• Don't create modes if phases suffice
• Don't add scripts if pure LLM can handle it
• Don't add directories you won't populate
• Start minimal, grow as needed