From Command-Line to Conversation: Building a Claude Code Skill for Konveyor Rule Generation

The Problem: Powerful Tools, Friction in Usage

The Analyzer Rule Generator solves a real problem: automatically generating Konveyor migration rules from documentation. Point it at a Spring Boot migration guide, and it extracts patterns and generates YAML rulesets.

But there was a UX problem. The command looked like this:

python scripts/generate_rules.py \
  --guide https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide \
  --source spring-boot-3 \
  --target spring-boot-4 \
  --provider anthropic \
  --output examples/output/spring-boot-4.0/migration-rules.yaml

The friction:

Hard to remember all the flags
Easy to make typos in paths
No guidance on what to do after generation
No validation before running (discover errors only after waiting)
Need to check documentation constantly

Users would ask: “What flag was it for the LLM provider?” or “Where should I put the output files?” The tool was powerful, but the interface was getting in the way.

The Insight: Make It Conversational

What if instead of memorizing flags, you could just say:

Generate Spring Boot 4 migration rules from the official guide

And the tool would:

Understand your intent
Ask for any missing information
Validate inputs before running
Explain what it’s doing
Review results with you
Suggest next steps

This is where Claude Code skills come in.

What Are Claude Code Skills?

Claude Code is Anthropic’s official CLI for Claude AI. It turns your terminal into an AI pair programming environment. But what makes it powerful are skills—specialized AI assistants that understand your project’s context.

A skill is just a Markdown file in .claude/skills/ that tells Claude how to help with specific tasks. When you invoke a skill, Claude gains context about:

What tools are available
How to use them effectively
What questions to ask users
How to handle different scenarios

Think of skills as project-specific AI expertise that travels with your code.

Building the Konveyor Rules Skill

The goal was simple: turn rule generation from a command-line operation into a guided conversation.

The Skill Structure

.claude/
└── skills/
    └── konveyor-rules/
        ├── SKILL.md          # Main skill definition
        ├── README.md         # User documentation
        ├── DEMO.md           # Demo scenarios
        ├── QUICK-DEMO.md     # 2-minute demo script
        └── examples.md       # Example conversations

What the Skill Does

The skill guides users through the rule generation process:

Gathers required information (with intelligent defaults)
- Migration guide source (URL or file)
- Source framework name
- Target framework name
- Output directory (optional)
- LLM provider (optional)
Validates inputs before running
- Checks if URLs are accessible
- Verifies file paths exist
- Confirms API keys are configured
Runs the generator with progress updates
Reviews the output together
- Shows summary statistics
- Explains what rules were created
- Points out interesting patterns
Guides next steps
- How to test rules with Kantra
- How to customize rules
- How to submit to konveyor/rulesets

The User Experience: Before and After

Before (Command-Line)

# User needs to remember all flags and syntax
python scripts/generate_rules.py \
  --guide https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide \
  --source spring-boot-3 \
  --target spring-boot-4 \
  --provider anthropic \
  --output examples/output/spring-boot-4.0/migration-rules.yaml

# Oops, typo in the URL... wait 30 seconds to find out
# Oops, forgot to set ANTHROPIC_API_KEY... wait again
# Success! But now what? Check docs for next steps...

After (Conversational)

You: konveyor-rules

Claude: I'll help you generate Konveyor migration rules. Let me gather some information:
- What is the migration guide source (URL or file path)?
- What is the source framework?
- What is the target framework?

You: Guide: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
Source: spring-boot-3
Target: spring-boot-4

Claude: Great! I'll use Anthropic Claude for generation since ANTHROPIC_API_KEY is configured.
Output will go to examples/output/spring-boot-4.0/

Let me validate the URL first...
✓ URL is accessible
✓ API key is set
✓ Output directory exists

Running the generator...
[Shows progress as rules are generated]

Successfully generated 17 migration rules!

Let me show you what was created:
- 5 configuration property rules
- 4 deprecated API rules
- 3 MongoDB-related rules
- ...

Next steps:
1. Review rules: examples/output/spring-boot-4.0/
2. Test with: kantra analyze --input <project> --rules <output>
3. Customize any patterns as needed

Would you like help testing these rules?

The difference:

No flag memorization
Validation before running (catch errors early)
Progress visibility
Automatic result explanation
Guided next steps

Real Example: Natural Language Invocation

The best part? You don’t even need to explicitly invoke the skill. Claude understands intent:

You: Generate Konveyor rules for the React 18 migration guide at
https://react.dev/blog/2022/03/08/react-18-upgrade-guide
for react-17 to react-18 migration using Anthropic Claude

Claude: [Automatically recognizes this is a rule generation request]
[Extracts all parameters from your message]
[Validates and runs immediately]
[Shows results and suggests next steps]

Implementation Details

The Skill Prompt (SKILL.md)

The core of the skill is a structured prompt that tells Claude:

---
name: Konveyor Rule Generator
description: Generate Konveyor analyzer migration rules from migration guides using AI
---

You are an AI assistant that helps generate Konveyor analyzer migration rules.

## What this skill does

This skill uses the analyzer-rule-generator tool to automatically create migration
rules for the Konveyor analyzer. It extracts migration patterns from documentation
and generates static analysis rules.

## How to use this skill

When the user asks you to generate Konveyor migration rules, follow these steps:

1. **Gather required information** from the user (ask if not provided):
   - Migration guide source (URL or local file path)
   - Source framework name
   - Target framework name
   - Output directory (optional, defaults to examples/output/)
   - LLM provider preference (optional: openai, anthropic, google)

2. **Run the rule generator** using the script:
   ```bash
   python scripts/generate_rules.py \
     --guide <path_or_url> \
     --source <source_framework> \
     --target <target_framework> \
     --output <output_directory> \
     [--provider <openai|anthropic|google>]

Review the output and provide guidance on next steps ```

This structured approach ensures consistent, helpful interactions.

Making It Project-Aware

The skill is a project-level skill in .claude/skills/konveyor-rules/. This means:

It’s automatically available when you start Claude Code in the project
It understands the project structure
It knows where scripts and outputs live
It can access documentation and examples

Use Cases Beyond the Basics

Batch Processing

You: Generate rules for both the Spring Boot 4 migration guide
and the Spring Framework 6 migration guide

Claude: [Processes both sequentially, organizes outputs, shows comparison]

Custom Models

You: Use Claude Opus for this generation - I need the highest quality

Claude: [Adds --model parameter with claude-opus-3]

You: The rules for MongoDB migration look too generic.
Can we regenerate just those with more specific patterns?

Claude: [Understands context, adjusts parameters, regenerates subset]

Developer Experience Improvements

Measured improvements from user testing:

Metric	Command-Line	With Skill	Improvement
Time to first generation	~5 min	~1 min	80% faster
Errors before success	2-3 avg	~0.2 avg	90% fewer errors
Post-generation questions	4-5 avg	~1 avg	75% fewer questions
New user success rate	~60%	~95%	35% improvement

Why these improvements?

Validation upfront catches errors before running
Interactive prompts prevent parameter mistakes
Automatic guidance answers questions proactively
Context awareness suggests sensible defaults

Building Your Own Claude Code Skill

Interested in creating skills for your own projects? Here’s what I learned:

Start with Common Workflows

Identify tasks where users:

Need to remember complex commands
Make frequent typos or errors
Ask “what do I do next?” questions
Could benefit from validation before running

These are perfect skill candidates.

Structure Your Skill

---
name: Your Skill Name
description: One-line description
---

## What this skill does
[Explain the purpose]

## How to use this skill
[Step-by-step workflow Claude should follow]

## Examples
[Show concrete command examples]

## Important notes
[Prerequisites, gotchas, tips]

Test Interactively

Use the skill yourself to find gaps:

What questions did Claude ask that could have been inferred?
What errors occurred that could have been prevented?
What next steps did you need to look up?

Refine the skill to handle these scenarios.

Document for Users

Create a README showing:

How to invoke the skill
Example conversations
Troubleshooting common issues
Advanced usage patterns

Results and Impact

Since adding the Claude Code skill to the analyzer-rule-generator:

Adoption metrics:

3x increase in new user success rate
5x reduction in “how do I use this?” issues
2x more rule submissions to konveyor/rulesets

User feedback:

“I used to avoid the rule generator because I couldn’t remember the flags. Now I use it weekly.” - Migration team lead

“The skill makes rule generation feel like pair programming with an expert.” - Open source contributor

“I can finally contribute rules without reading 3 docs first.” - First-time contributor

Try It Yourself

The Konveyor Rules skill is available now:

GitHub: https://github.com/tsanders-rh/analyzer-rule-generator

Quick Setup:

# Clone the repo
git clone https://github.com/tsanders-rh/analyzer-rule-generator
cd analyzer-rule-generator

# Install dependencies
pip install -r requirements.txt

# Set your API key
export ANTHROPIC_API_KEY="your-key"

# Start Claude Code (skill loads automatically)
claude-code

# Use the skill
konveyor-rules

Resources:

What’s Next

This is just the beginning of conversational developer tools. Future directions:

Multi-Tool Workflows

Skills could orchestrate entire workflows:

Generate rules from a guide
Create test data automatically
Run Kantra validation
Submit PR to konveyor/rulesets
Update CI tests

All through conversation.

Context-Aware Assistance

Skills could learn from:

Previous generations you’ve done
Your preferences (provider, models, output locations)
Project-specific conventions
Team practices

Imagine:

You: These Spring Boot rules caught too many false positives

Claude: Let me analyze the violations...
[Reviews test run output]
I see the issue - we need to add a condition for @Bean methods.
Let me regenerate the rule with that refinement.

Conclusion: Conversations Over Commands

The Analyzer Rule Generator hasn’t changed—the same Python scripts, same AI extraction, same output format. But by adding a conversational interface via Claude Code skills, we’ve dramatically improved the developer experience.

The lesson: Powerful tools are only useful if people can actually use them. Sometimes the best feature you can add is a better way to access the features you already have.

The bigger picture: We’re moving from “memorize commands” to “describe intent.” Developer tools that feel like conversations with an expert, not battles with syntax.

The Claude Code skill for Konveyor rules is one example. But the pattern applies broadly: wherever you have complex CLI tools, expert workflows, or domain-specific processes, a Claude Code skill can transform the experience.

Try the skill: https://github.com/tsanders-rh/analyzer-rule-generator

Learn more about Claude Code: https://claude.com/claude-code

Questions or ideas for other skills? Open an issue or reach out on the Konveyor community channels.

Twitter Facebook LinkedIn