Ruby Skill Creator

Create Claude Code Skills where Ruby serves as the orchestration and control flow language.

Overview

This skill enables authoring new Skills using Ruby code to implement:

• Conditional logic - IF/THEN branching based on user input or context
• Control flow - Loops, switches, and dynamic routing
• Variable management - Constants and state that influence behavior
• File orchestration - Programmatic reference to cookbook/prompt/tool files
• Dynamic output - Generate instructions based on runtime evaluation

Skill Structure

.claude/skills/skill-name/
├── SKILL.md              # Entry point - loads and executes skill.rb
├── skill.rb              # Main Ruby skill definition (required)
├── cookbook/             # Instruction modules loaded conditionally
│   ├── variant_a.md
│   └── variant_b.md
├── prompts/              # User-facing prompt templates
│   └── example_prompt.md
├── tools/                # Ruby helper scripts and utilities
│   ├── helpers.rb
│   └── validators.rb
└── references/           # Domain knowledge loaded as needed
    └── api_docs.md

Ruby Skill Definition API

The skill.rb file defines skill behavior using a Ruby DSL. Claude reads and interprets this file to determine how to proceed.

Core DSL Methods

# skill.rb - Main skill definition

# Constants influencing control flow
CONSTANTS = {
  output_format: "markdown",      # markdown | json | html
  strict_mode: true,              # Enable validation
  max_iterations: 5,              # Loop limits
  default_variant: "standard"     # Default cookbook variant
}

# Entry point - Claude calls this to begin
def execute(context)
  # context.user_input   - The user's request
  # context.files        - Uploaded files
  # context.conversation - Conversation history
  
  variant = determine_variant(context.user_input)
  load_cookbook(variant)
  
  if context.files.any?
    process_files(context.files)
  end
  
  generate_output(context)
end

# Conditional cookbook loading
def determine_variant(input)
  case input
  when /fast|quick|simple/i
    "lightweight"
  when /detailed|comprehensive|thorough/i
    "comprehensive"
  when /api|integration|connect/i
    "api_integration"
  else
    CONSTANTS[:default_variant]
  end
end

# Load cookbook instructions
def load_cookbook(variant)
  cookbook_path = "cookbook/#{variant}.md"
  read_file(cookbook_path)
end

# Conditional file processing
def process_files(files)
  files.each do |file|
    case file.extension
    when ".pdf"
      load_tool("tools/pdf_processor.rb")
    when ".csv", ".xlsx"
      load_tool("tools/data_processor.rb")
    when ".rb", ".py", ".js"
      load_tool("tools/code_analyzer.rb")
    end
  end
end

# Dynamic output generation
def generate_output(context)
  template = read_file("prompts/output_template.md")
  
  if CONSTANTS[:strict_mode]
    validate_output(template)
  end
  
  render(template, context)
end

Available DSL Methods

Control Flow Patterns

Pattern 1: Conditional Cookbook Selection

def execute(context)
  cookbook = case
    when context.user_input.match?(/create|new|generate/)
      "creation"
    when context.user_input.match?(/edit|modify|update/)
      "modification"
    when context.user_input.match?(/analyze|review|check/)
      "analysis"
    else
      "general"
  end
  
  load_cookbook(cookbook)
  emit "Follow the #{cookbook} workflow above."
end

Pattern 2: Multi-Step Workflow

WORKFLOW_STEPS = [:gather, :validate, :process, :output]

def execute(context)
  state = { current_step: 0, data: {} }
  
  WORKFLOW_STEPS.each_with_index do |step, index|
    state[:current_step] = index
    
    case step
    when :gather
      load_cookbook("gather_requirements")
      state[:data][:requirements] = gather_from_user(context)
    when :validate
      load_tool("tools/validator.rb")
      unless validate(state[:data][:requirements])
        emit "Validation failed. Please review requirements."
        return
      end
    when :process
      load_cookbook("processing")
      state[:data][:result] = process(state[:data][:requirements])
    when :output
      load_prompt("final_output")
      render_final(state[:data])
    end
  end
end

Pattern 3: Feature Flags

FEATURES = {
  enhanced_validation: true,
  experimental_output: false,
  strict_formatting: true,
  verbose_logging: false
}

def execute(context)
  load_cookbook("base")
  
  if FEATURES[:enhanced_validation]
    load_cookbook("validation_enhanced")
  end
  
  if FEATURES[:experimental_output]
    load_cookbook("output_experimental")
  else
    load_cookbook("output_standard")
  end
  
  if FEATURES[:strict_formatting]
    emit "Apply strict formatting rules from cookbook."
  end
end

Pattern 4: Input-Driven Routing

ROUTES = {
  /\b(pdf|document)\b/i => "document_processing",
  /\b(image|photo|picture)\b/i => "image_handling",
  /\b(data|csv|excel)\b/i => "data_analysis",
  /\b(code|script|program)\b/i => "code_review"
}

def execute(context)
  route = ROUTES.find { |pattern, _| context.user_input.match?(pattern) }
  
  if route
    cookbook_name = route[1]
    load_cookbook(cookbook_name)
    emit "Proceeding with #{cookbook_name} workflow."
  else
    load_cookbook("general")
    emit "Using general workflow. Clarify if specific handling needed."
  end
end

Creating a New Ruby-Based Skill

Step 1: Initialize Structure

Create the skill directory:

mkdir -p .claude/skills/my-skill/{cookbook,prompts,tools,references}
touch .claude/skills/my-skill/{SKILL.md,skill.rb}

Step 2: Write SKILL.md

The SKILL.md serves as the entry point and instructs Claude to load skill.rb:

---
name: my-skill-name
description: Clear description of what this skill does and when to trigger it.
---

# My Skill Name

This skill uses Ruby for control flow. Execute the skill definition:

1. Read `skill.rb` to understand the skill's logic
2. Evaluate the Ruby code conceptually to determine workflow
3. Follow the control flow to load appropriate cookbook/prompt/tool files
4. Execute instructions from loaded files

## Entry Point

\`\`\`ruby
# See skill.rb for full implementation
load "skill.rb"
execute(context)
\`\`\`

Step 3: Implement skill.rb

Define the skill logic in Ruby:

# skill.rb

CONSTANTS = {
  version: "1.0.0",
  default_mode: "standard"
}

def execute(context)
  mode = detect_mode(context.user_input)
  load_cookbook(mode)
  
  if requires_tools?(context)
    load_required_tools(context)
  end
  
  generate_response(context, mode)
end

def detect_mode(input)
  # Mode detection logic
end

def requires_tools?(context)
  # Tool requirement check
end

def load_required_tools(context)
  # Dynamic tool loading
end

def generate_response(context, mode)
  # Response generation
end

Step 4: Create Cookbook Files

Add markdown instruction files in cookbook/:

<!-- cookbook/standard.md -->
# Standard Mode Instructions

When operating in standard mode:

1. Analyze the user's request
2. Apply default formatting rules
3. Generate output following standard template

## Guidelines

- Keep responses concise
- Use consistent formatting
- Validate output before presenting

Step 5: Add Prompts and Tools

Create prompt templates and Ruby helper tools as needed:

<!-- prompts/output_template.md -->
# Output Template

## Summary
{{summary}}

## Details
{{details}}

## Next Steps
{{next_steps}}

# tools/validator.rb

def validate_output(content)
  errors = []
  
  errors << "Missing summary" unless content.include?("## Summary")
  errors << "Too short" if content.length < 100
  
  { valid: errors.empty?, errors: errors }
end

Example: Complete Ruby-Based Skill

See references/complete_example.md for a fully implemented example skill demonstrating all patterns.

Best Practices

1. Keep skill.rb focused - Logic only, not content. Content lives in cookbook/prompts.
2. Use meaningful CONSTANTS - Document what each constant controls.
3. Prefer pattern matching - Ruby's case/when and regex matching for routing.
4. Load files lazily - Only load cookbook/tools when the branch is taken.
5. Provide fallbacks - Always have a default/else branch.
6. Comment control flow - Explain why branches exist, not what they do.

Interpreting Ruby Skills

When Claude encounters a Ruby-based skill:

1. Parse skill.rb - Understand the defined methods and control flow
2. Identify entry point - Find the execute(context) method
3. Trace execution - Follow the logic path based on current context
4. Load referenced files - When load_cookbook, load_tool, etc. are called
5. Execute instructions - Follow the loaded markdown instructions
6. Apply CONSTANTS - Respect configuration values in decision-making

Claude interprets the Ruby conceptually - it does not run a Ruby interpreter, but understands the logic to determine which files to load and what instructions to follow.