code-examples

What this skill does

# Code Examples Skill v2.0

## Skill Identity

```yaml
skill_id: code-examples
type: specialized_skill
domain: technical_documentation
responsibility: Generate and validate code examples
atomicity: single-purpose
```

## Input/Output Schemas

### Input Schema

```typescript
interface CodeExampleInput {
  // Required
  example_type: 'basic' | 'integration' | 'configuration' | 'error_handling' | 'full_project';
  languages: string[];  // ['javascript', 'python', 'go', etc.]

  // Context
  context?: {
    api_endpoint?: string;
    library_name?: string;
    framework?: string;
    use_case?: string;
  };

  // Complexity
  complexity?: 'beginner' | 'intermediate' | 'advanced';

  // Content options
  include_tests?: boolean;
  include_error_handling?: boolean;
  include_comments?: boolean;
  include_type_hints?: boolean;

  // Structure
  structure?: {
    max_lines_per_example?: number;
    include_imports?: boolean;
    include_main?: boolean;
    include_output?: boolean;
  };

  // Quality
  quality?: {
    lint_check?: boolean;
    security_check?: boolean;
    style_guide?: string;  // 'google', 'airbnb', 'pep8', etc.
  };
}
```

### Output Schema

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

  // Generated examples
  examples: LanguageExample[];

  // Validation results
  validation: {
    syntax_valid: boolean;
    all_imports_valid: boolean;
    security_issues: SecurityIssue[];
    lint_warnings: LintWarning[];
  };

  // Quality metrics
  quality: {
    readability_score: number;     // 0-100
    maintainability_score: number; // 0-100
    documentation_score: number;   // 0-100
    test_coverage: number;         // 0-100 (if tests included)
  };

  // Metadata
  metadata: {
    languages_generated: string[];
    total_lines: number;
    processing_time_ms: number;
  };
}

interface LanguageExample {
  language: string;
  code: string;
  explanation: string;
  imports?: string[];
  dependencies?: Dependency[];
  run_command?: string;
  expected_output?: string;
  test_code?: string;
}

interface Dependency {
  name: string;
  version: string;
  install_command: string;
}
```

## Parameter Validation Rules

```yaml
validation_rules:
  example_type:
    type: string
    required: true
    enum: [basic, integration, configuration, error_handling, full_project]
    error_message: "example_type must be one of: basic, integration, configuration, error_handling, full_project"

  languages:
    type: array
    required: true
    min_items: 1
    max_items: 10
    items:
      type: string
      enum: [javascript, typescript, python, go, rust, java, csharp, php, ruby, kotlin, swift]

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

  structure.max_lines_per_example:
    type: integer
    required: false
    default: 100
    min: 10
    max: 500

  quality.style_guide:
    type: string
    required: false
    enum: [google, airbnb, pep8, standard, prettier]
```

## 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: 'code-examples',
        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(
    'CODE_EXAMPLE_GENERATION_FAILED',
    `Failed after ${config.max_attempts} attempts`,
    lastError
  );
}
```

## Logging & Observability Hooks

### Pre-Execution Hook

```typescript
function preExecutionHook(input: CodeExampleInput, context: ExecutionContext): void {
  log.info({
    event: 'skill_invocation_start',
    skill: 'code-examples',
    trace_id: context.trace_id,
    input_summary: {
      example_type: input.example_type,
      languages: input.languages,
      complexity: input.complexity
    }
  });

  metrics.startTimer('code_example_generation_duration');
  metrics.increment('code_example_invocations_total', {
    example_type: input.example_type,
    language_count: input.languages.length.toString()
  });

  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: CodeExampleOutput,
  context: ExecutionContext,
  duration: number
): void {
  log.info({
    event: 'skill_invocation_complete',
    skill: 'code-examples',
    trace_id: context.trace_id,
    status: output.status,
    metrics: {
      duration_ms: duration,
      languages: output.metadata.languages_generated,
      total_lines: output.metadata.total_lines,
      syntax_valid: output.validation.syntax_valid
    }
  });

  metrics.stopTimer('code_example_generation_duration');
  metrics.record('code_example_quality_score', output.quality.readability_score);

  if (!output.validation.syntax_valid) {
    log.warn({
      event: 'syntax_validation_failed',
      languages: output.metadata.languages_generated
    });
  }

  if (output.validation.security_issues.length > 0) {
    log.warn({
      event: 'security_issues_detected',
      count: output.validation.security_issues.length,
      issues: output.validation.security_issues
    });
  }
}
```

## Language-Specific Templates

### JavaScript/TypeScript

```typescript
// Template: API Integration
interface APIConfig {
  baseURL: string;
  apiKey: string;
  timeout?: number;
}

class APIClient {
  private config: APIConfig;
  private client: AxiosInstance;

  constructor(config: APIConfig) {
    this.config = config;
    this.client = axios.create({
      baseURL: config.baseURL,
      timeout: config.timeout || 30000,
      headers: {
        'Authorization': `Bearer ${config.apiKey}`,
        'Content-Type': 'application/json'
      }
    });
  }

  async get<T>(endpoint: string, params?: Record<string, any>): Promise<T> {
    try {
      const response = await this.client.get<T>(endpoint, { params });
      return response.data;
    } catch (error) {
      this.handleError(error);
      throw error;
    }
  }

  async post<T, D>(endpoint: string, data: D): Promise<T> {
    try {
      const response = await this.client.post<T>(endpoint, data);
      return response.data;
    } catch (error) {
      this.handleError(error);
      throw error;
    }
  }

  private handleError(error: AxiosError): void {
    if (error.response) {
      console.error(`API Error: ${error.response.status}`, error.response.data);
    } else if (error.request) {
      console.error('Network Error: No response received');
    } else {
      console.error('Request Error:', error.message);
    }
  }
}

// Usage
const client = new APIClient({
  baseURL: 'https://api.example.com/v1',
  apiKey: process.env.API_KEY!
});

const users = await client.get<User[]>('/users');
```

### Python

```python
# Template: API Integration
from typing import Optional, Dict, Any, TypeVar, Generic
from dataclasses import dataclass
import httpx
import logging

T = TypeVar('T')

@dataclass
class APIConfig:
    base_url: str
    api_key: str
    timeout: int = 30

class APIClient:
    """Production-ready API client with error handling and retry logic."""

    def __init__(self, config: APIConfig):
        self.config = config
        self.logger = logging.getLogger(__name__)
        self.client = httpx.Client(
            b