user-guides

What this skill does

# User Guides & Tutorials Skill v2.0

## Skill Identity

```yaml
skill_id: user-guides
type: specialized_skill
domain: technical_documentation
responsibility: Generate user-focused documentation and tutorials
atomicity: single-purpose
```

## Input/Output Schemas

### Input Schema

```typescript
interface UserGuideInput {
  // Required
  guide_type: 'getting_started' | 'tutorial' | 'feature_guide' | 'troubleshooting' | 'faq' | 'reference';

  // Content source
  source?: {
    product_name: string;
    product_version?: string;
    feature_list?: string[];
    existing_docs?: string;
    ui_screenshots?: string[];
  };

  // Target audience
  target_audience?: 'beginner' | 'intermediate' | 'advanced' | 'mixed';

  // Output preferences
  output_format?: 'markdown' | 'html' | 'rst' | 'docx';

  // Content options
  include_screenshots?: boolean;
  include_troubleshooting?: boolean;
  include_faq?: boolean;
  include_next_steps?: boolean;

  // Structure options
  structure?: {
    max_sections?: number;
    max_steps_per_section?: number;
    heading_style?: 'atx' | 'setext';
    numbered_steps?: boolean;
  };

  // Quality requirements
  quality?: {
    min_reading_level?: number;    // Flesch-Kincaid grade level
    max_paragraph_length?: number; // words
    require_examples?: boolean;
    require_callouts?: boolean;
  };
}
```

### Output Schema

```typescript
interface UserGuideOutput {
  status: 'success' | 'partial_success' | 'failed';

  // Generated content
  content: {
    title: string;
    sections: Section[];
    full_document: string;
  };

  // Structure metadata
  structure: {
    section_count: number;
    total_steps: number;
    word_count: number;
    reading_time_minutes: number;
  };

  // Quality metrics
  quality: {
    readability_score: number;     // 0-100 (Flesch Reading Ease)
    clarity_score: number;         // 0-100
    completeness_score: number;    // 0-100
    accessibility_score: number;   // 0-100
  };

  // Validation
  validation: {
    is_valid: boolean;
    issues: ValidationIssue[];
    suggestions: Suggestion[];
  };

  // Execution metadata
  metadata: {
    guide_type: string;
    target_audience: string;
    processing_time_ms: number;
  };
}

interface Section {
  title: string;
  content: string;
  steps?: Step[];
  subsections?: Section[];
}

interface Step {
  number: number;
  instruction: string;
  expected_result?: string;
  screenshot?: string;
  tip?: string;
}
```

## Parameter Validation Rules

```yaml
validation_rules:
  guide_type:
    type: string
    required: true
    enum: [getting_started, tutorial, feature_guide, troubleshooting, faq, reference]
    error_message: "guide_type must be one of: getting_started, tutorial, feature_guide, troubleshooting, faq, reference"

  target_audience:
    type: string
    required: false
    default: mixed
    enum: [beginner, intermediate, advanced, mixed]

  output_format:
    type: string
    required: false
    default: markdown
    enum: [markdown, html, rst, docx]

  source.product_name:
    type: string
    required: true
    min_length: 2
    max_length: 100

  structure.max_sections:
    type: integer
    required: false
    default: 10
    min: 1
    max: 50

  quality.min_reading_level:
    type: number
    required: false
    default: 8
    min: 1
    max: 18
    description: "Flesch-Kincaid grade level target"
```

## Retry Logic

```typescript
async function executeWithRetry<T>(
  operation: () => Promise<T>,
  config: RetryConfig
): Promise<T> {
  let lastError: Error;
  let delay = config.backoff.initial_delay_ms;

  for (let attempt = 1; attempt <= config.max_attempts; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;

      if (!isRetryableError(error)) {
        throw error;
      }

      log.warn({
        skill: 'user-guides',
        attempt,
        max_attempts: config.max_attempts,
        delay_ms: delay,
        error: error.message
      });

      if (attempt < config.max_attempts) {
        await sleep(delay);
        delay = Math.min(
          delay * config.backoff.multiplier,
          config.backoff.max_delay_ms
        );
      }
    }
  }

  throw new SkillExecutionError(
    'GUIDE_GENERATION_FAILED',
    `Failed after ${config.max_attempts} attempts`,
    lastError
  );
}
```

## Logging & Observability Hooks

### Pre-Execution Hook

```typescript
function preExecutionHook(input: UserGuideInput, context: ExecutionContext): void {
  log.info({
    event: 'skill_invocation_start',
    skill: 'user-guides',
    trace_id: context.trace_id,
    input_summary: {
      guide_type: input.guide_type,
      target_audience: input.target_audience,
      product: input.source?.product_name
    }
  });

  metrics.startTimer('guide_generation_duration');
  metrics.increment('guide_invocations_total', {
    guide_type: input.guide_type,
    audience: input.target_audience
  });

  const validation = validateInput(input);
  if (!validation.valid) {
    log.error({ event: 'input_validation_failed', errors: validation.errors });
    throw new ValidationError(validation.errors);
  }
}
```

### Post-Execution Hook

```typescript
function postExecutionHook(
  output: UserGuideOutput,
  context: ExecutionContext,
  duration: number
): void {
  log.info({
    event: 'skill_invocation_complete',
    skill: 'user-guides',
    trace_id: context.trace_id,
    status: output.status,
    metrics: {
      duration_ms: duration,
      sections: output.structure.section_count,
      readability: output.quality.readability_score
    }
  });

  metrics.stopTimer('guide_generation_duration');
  metrics.record('guide_readability_score', output.quality.readability_score);
  metrics.record('guide_word_count', output.structure.word_count);

  if (output.quality.readability_score < 60) {
    log.warn({
      event: 'low_readability',
      score: output.quality.readability_score,
      suggestion: 'Consider simplifying language'
    });
  }
}
```

## Guide Templates

### Getting Started Guide Template

```markdown
# Getting Started with ${product_name}

## Overview
${brief_description}

**What you'll accomplish:**
- ${objective_1}
- ${objective_2}
- ${objective_3}

**Prerequisites:**
- ${prerequisite_1}
- ${prerequisite_2}

**Estimated time:** ${estimated_time} minutes

---

## Step 1: ${step_1_title}

${step_1_description}

${step_1_instructions}

> **Expected result:** ${step_1_expected_result}

---

## Step 2: ${step_2_title}

${step_2_description}

${step_2_instructions}

> **Tip:** ${step_2_tip}

---

## Step 3: ${step_3_title}

${step_3_description}

${step_3_instructions}

---

## Verify Your Setup

To confirm everything is working:

1. ${verification_step_1}
2. ${verification_step_2}

**Success indicators:**
- ✅ ${success_indicator_1}
- ✅ ${success_indicator_2}

---

## Troubleshooting

### Common Issue: ${common_issue_1}
**Solution:** ${solution_1}

### Common Issue: ${common_issue_2}
**Solution:** ${solution_2}

---

## Next Steps

Now that you're set up, explore:
- [${next_step_1}](${link_1})
- [${next_step_2}](${link_2})
- [${next_step_3}](${link_3})

---

## Need Help?

- 📚 [Full Documentation](${docs_link})
- 💬 [Community Forum](${forum_link})
- 📧 [Contact Support](${support_link})
```

### Tutorial Template

```markdown
# Tutorial: ${tutorial_title}

## What You'll Learn

By the end of this tutorial, you will:
- ${learning_objective_1}
- ${learning_objective_2}
- ${learning_objective_3}

## Prerequisites

Before starting, ensure you have:
- [ ] ${prerequisite_1}
- [ ] ${prerequisite_2}
- [ ] ${prerequisite_3}

**Estimated time:** ${estimated_time} minutes

---

## Part 1: ${part_1_title}

### Understanding ${concept}

${concept_explanation}

**Why this matters:**
${importance_explanation}

### Hands-On: ${hands_on_task}

#### Step 1: ${step_1}
${step_1_details}

\`\`\`${language}
${code_example_1}
\`\`\`

#### Step 2: ${step_2}
${step_2_details}

\`\`\`${language}
${code_example_2}