# Claude Code Skills for Kafka Schema Registry MCP

This directory contains custom skills designed specifically for the Kafka Schema Registry MCP Server project. These skills provide specialized workflows and automation for common development tasks.

## Available Skills

### 1. Schema Development Skills

#### `/schema-generate`
Generate production-ready Avro schemas from natural language descriptions.

```
/schema-generate event UserRegistered "user registration with userId, email, method"
/schema-generate entity Product "product with id, name, price, inventory"
/schema-generate command CreateOrder "create order with customer, items, payment"
/schema-generate aggregate Order "order managing line items and payments"
```

**Use when:**
- Starting a new schema from scratch
- Need to follow project templates
- Want AI assistance with schema design

---

#### `/schema-evolve`
Safely evolve existing schemas with automatic compatibility checking.

```
/schema-evolve user-profile "add optional phoneNumber field"
/schema-evolve order-event "add REFUNDED enum value"
/schema-evolve product-entity "rename description to productDescription"
```

**Use when:**
- Modifying existing schemas
- Ensuring backward compatibility
- Need migration guidance

---

### 2. Operations Skills

#### `/context-compare`
Compare schemas between contexts to identify differences and plan synchronization.

```
/context-compare development staging
/context-compare staging production --detailed
/context-compare development production --only-differences
```

**Use when:**
- Before deploying to higher environments
- Detecting schema drift between contexts
- Auditing environment synchronization
- Planning releases and promotions

---

#### `/migration-plan`
Generate comprehensive migration plans for moving schemas between contexts or registries.

```
/migration-plan development staging
/migration-plan staging production --with-rollback
/migration-plan registry-a registry-b --dry-run
```

**Use when:**
- Promoting schemas to higher environments
- Setting up disaster recovery
- Consolidating registries
- Need step-by-step migration process

---

### 3. Quality Assurance Skills

#### `/lint-and-test`
Run comprehensive linting and testing workflow with auto-fix capabilities.

```
/lint-and-test quick          # Quick lint check (2-3s)
/lint-and-test fix            # Auto-fix formatting (20-30s)
/lint-and-test ci             # CI mirror check (10-15s)
/lint-and-test test-quick     # Lint + quick tests (5 min)
/lint-and-test test-full      # Lint + full suite (15 min)
/lint-and-test pre-commit     # Pre-commit workflow
/lint-and-test pre-push       # Pre-push workflow
```

**Use when:**
- Before every commit
- Before every push
- Before creating pull requests
- When you have lint/test failures

---

## Skill Categories

### Schema Development
- **Purpose:** Create and evolve schemas efficiently
- **Skills:** schema-generate, schema-evolve
- **Output:** Production-ready Avro schemas

### Operations
- **Purpose:** Manage schema migrations and deployments
- **Skills:** migration-plan
- **Output:** Detailed migration plans with rollback procedures

### Quality Assurance
- **Purpose:** Ensure code quality and test coverage
- **Skills:** lint-and-test
- **Output:** Lint reports and test results

---

## Quick Start

### First Time Setup

1. **Generate your first schema:**
   ```
   /schema-generate event UserCreated "user creation event with userId, email, timestamp"
   ```

2. **Run lint check:**
   ```
   /lint-and-test quick
   ```

3. **Fix any issues:**
   ```
   /lint-and-test fix
   ```

### Daily Workflow

**Morning:**
```
/lint-and-test quick    # Verify clean starting point
```

**During Development:**
```
/schema-generate event OrderPlaced "order placement with orderId, items, total"
/schema-evolve user-profile "add loyaltyPoints field"
/lint-and-test quick    # After making changes
```

**Before Commit:**
```
/lint-and-test pre-commit
git commit -m "feat: add order placement schema"
```

**Before Push:**
```
/lint-and-test pre-push
git push origin your-branch
```

**Before Production:**
```
/migration-plan staging production --with-rollback
```

---

## Skill Invocation Methods

### Method 1: Direct Command
```
/schema-generate event UserRegistered "..."
```

### Method 2: Natural Language
```
"Generate a user registration event schema with userId, email, and timestamp"
```
I'll automatically invoke the appropriate skill.

### Method 3: Interactive
```
"I need to create a new schema"
```
I'll ask clarifying questions and invoke the right skill.

---

## Common Workflows

### Workflow 1: New Feature Development
```
1. /schema-generate event FeatureEvent "..."
2. Review and customize generated schema
3. /lint-and-test quick
4. Register schema to development context
5. /lint-and-test pre-commit
6. git commit
```

### Workflow 2: Schema Evolution
```
1. /schema-evolve existing-schema "add new field"
2. Review compatibility assessment
3. Test in development context
4. /lint-and-test test-quick
5. /lint-and-test pre-commit
6. git commit
```

### Workflow 3: Environment Promotion
```
1. /migration-plan development staging
2. Review migration plan
3. Execute migration during maintenance window
4. Validate migration success
5. /migration-plan staging production
6. Repeat for production
```

### Workflow 4: Pre-Commit
```
1. Make code changes
2. /lint-and-test quick
3. If issues → /lint-and-test fix
4. git diff (review changes)
5. /lint-and-test quick (verify)
6. git commit
```

### Workflow 5: Pre-Push
```
1. /lint-and-test ci
2. If fails → fix issues
3. /lint-and-test test-quick (optional)
4. git push
```

---

## Skill Output Locations

### Generated Files

**Schemas:**
- Generated schemas are displayed in output
- Save to appropriate location for registration
- Include in git commits

**Migration Plans:**
- Saved to `migrations/` directory (auto-created)
- Include timestamps and metadata
- Version controlled

**Test Reports:**
- Saved to `tests/reports/` directory
- Not version controlled (in .gitignore)
- Useful for debugging

**Lint Reports:**
- Displayed in terminal output
- Auto-fixes applied directly to files
- Review with `git diff`

---

## Skill Configuration

### Environment Variables

Skills respect these environment variables:

```bash
# Schema Registry
SCHEMA_REGISTRY_URL=http://localhost:8081
DEFAULT_CONTEXT=development

# MCP Server
MCP_SERVER_PORT=38000

# Testing
SLIM_MODE=false
```

### Project Configuration

Skills read from:
- `.claude-code/config.json` - Main configuration
- `.claude-code/workspace.json` - Workspace settings
- `.claude-code/templates/` - Schema templates
- `pyproject.toml` - Lint configurations

---

## Best Practices

### Schema Generation
1. ✅ Use descriptive names for schemas
2. ✅ Include field-level documentation in descriptions
3. ✅ Specify enum values when applicable
4. ✅ Indicate required vs optional fields
5. ✅ Review generated schema before registering

### Schema Evolution
1. ✅ Always check compatibility first
2. ✅ Test in development context
3. ✅ Add defaults to optional fields
4. ✅ Document breaking changes
5. ✅ Plan rollback strategy

### Migration Planning
1. ✅ Use `--dry-run` first
2. ✅ Review plan before executing
3. ✅ Backup before production migration
4. ✅ Migrate during maintenance windows
5. ✅ Validate after migration

### Linting and Testing
1. ✅ Run quick lint frequently (it's fast!)
2. ✅ Fix lint issues immediately
3. ✅ Never push with lint failures
4. ✅ Run tests before pull requests
5. ✅ Keep virtual environment activated

---

## Troubleshooting

### Skill Not Found
```
Error: Unknown skill /schema-generate
Fix: Ensure you're using the correct syntax with forward slash
```

### Permission Errors
```
Error: Permission denied
Fix: Check file permissions on skill files
      chmod +x .claude-code/skills/*.md
```

### Template Not Found
```
Error: Template 'event' not found
Fix: Verify templates exist in .claude-code/templates/
      ls .claude-code/templates/
```

### Lint Check Fails
```
Error: Black would reformat files
Fix: /lint-and-test fix
```

### Test Failures
```
Error: Docker not running
Fix: Start Docker Desktop
```

---

## Extending Skills

### Creating New Skills

1. Create new skill file in `.claude-code/skills/`
2. Follow the naming convention: `skill-name.md`
3. Include these sections:
   - Skill Name and Description
   - Purpose
   - Usage and Examples
   - What This Skill Does
   - Output
   - Related Skills
   - Best Practices

4. Update this README.md

### Skill File Template

```markdown
# Your Skill Name

**Skill Name:** `/your-skill`
**Category:** Category Name
**Description:** Brief description

## Purpose
Why this skill exists

## Usage
How to invoke it with examples

## What This Skill Does
Step-by-step what happens

## Output
What the skill produces

## Related Skills
Links to related skills

## Best Practices
Tips for using this skill
```

---

## Related Documentation

- **GETTING_STARTED.md** - Contributor guide
- **AGENTS.md** - Development guidelines
- **TESTING_SETUP_GUIDE.md** - Testing documentation
- **.claude-code/README.md** - Claude Code usage guide
- **docs/api-reference.md** - API documentation

---

## Support

For issues or questions:
- Check skill documentation above
- Review GETTING_STARTED.md
- See AGENTS.md for development guidelines
- Check project documentation in `docs/`

---

## Version

Skills version: 1.0.0
Last updated: 2026-01-17
Compatible with: Claude Code, Kafka Schema Registry MCP v2.1.5

---

## Summary

You now have 5 powerful skills at your disposal:

1. **`/schema-generate`** - Create schemas from descriptions
2. **`/schema-evolve`** - Safely evolve existing schemas
3. **`/migration-plan`** - Plan schema migrations
4. **`/lint-and-test`** - Ensure code quality
5. **`/context-compare`** - Compare and analyze context changes

These skills are designed to work together to provide a seamless development experience for the Kafka Schema Registry MCP project.

**Start using them now!** Try `/schema-generate event UserRegistered "..."` to create your first schema.