Test Skill Example for Konflux CI Skills Repository

This directory contains a production-ready example skill that can be contributed to the Konflux CI Skills repository at https://github.com/konflux-ci/skills.

---

📁 What's Included

This example demonstrates how to create a complete, high-quality skill for Claude Code following Konflux CI conventions.

Directory Structure

test-skill-example/
├── .claude-plugin/
│   └── marketplace.json           # Plugin marketplace metadata
├── debugging-kubernetes-incidents/
│   ├── SKILL.md                   # Main skill content (the skill itself)
│   ├── README.md                  # Skill documentation
│   └── tests/
│       ├── scenarios.yaml         # Test scenario definitions (6 tests)
│       └── README.md              # Test documentation
├── CONTRIBUTION_GUIDE.md          # Step-by-step guide to contribute to Konflux
└── README.md                      # This file

---

🎯 About the Example Skill

Skill: debugging-kubernetes-incidents

Purpose: Teaches Claude Code systematic investigation and root cause analysis of Kubernetes incidents.

Key Features:

• ✅ 5-phase investigation methodology
• ✅ Multi-source correlation (logs, events, metrics)
• ✅ Common issue patterns (CrashLoopBackOff, OOMKilled, etc.)
• ✅ Decision trees and troubleshooting matrix
• ✅ Read-only investigation approach
• ✅ Real-world examples

Quality Metrics:

• Word Count: ~1,400 words (technique skill target: <1,000 words)
• Frontmatter: 248 characters (under 1,024 limit)
• Test Scenarios: 6 comprehensive tests
• Format: Follows all Konflux conventions

Source: Extracted from the SRE Copilot plugin - a general-purpose SRE toolkit for Claude Code.

---

🚀 How to Use This Example

Option 1: Study the Format

Use this as a reference when creating your own skills:

1. Review SKILL.md - See proper frontmatter, section structure, formatting
2. Check README.md - Understand documentation requirements
3. Examine tests/ - Learn test-driven development for documentation
4. Study marketplace.json - See plugin metadata format

Option 2: Contribute This Skill

Follow the CONTRIBUTION_GUIDE.md to submit this skill to Konflux:

# Quick start
cd debugging-kubernetes-incidents
# Follow steps in CONTRIBUTION_GUIDE.md

Option 3: Fork and Customize

Use this as a template for your own skill:

1. Copy the directory structure
2. Replace content with your skill
3. Update tests to match your skill's focus
4. Follow Konflux conventions
5. Contribute to Konflux repository

---

📊 Skill Compliance Check

This example skill meets all Konflux CI requirements:

✅ Required Files

• SKILL.md with proper YAML frontmatter
• README.md with skill documentation
• tests/scenarios.yaml with test definitions
• tests/README.md with test documentation

✅ Naming Conventions

• Directory name: debugging-kubernetes-incidents (kebab-case, gerund)
• Frontmatter name matches directory
• Technique skill uses gerund (-ing form)

✅ Content Requirements

• Frontmatter starts with "Use when..."
• Description written in third person
• Frontmatter under 1,024 characters
• Word count appropriate for technique skill
• Essential sections included (Overview, When to Use, etc.)

✅ Formatting Standards

• Uses bold for critical terms
• Uses ✓ and ✗ for correct/incorrect
• Uses backticks for technical terms
• Uses tables with | separators
• Uses CRITICAL: for warnings

✅ Testing Requirements

• 3-6 test scenarios (has 6)
• Each test has baseline failure documented
• Realistic user prompts
• Clear expected outputs
• Test documentation (tests/README.md)

✅ Quality Validation

• Schema validation passes (frontmatter format)
• JSON syntax valid (marketplace.json)
• Source paths start with ./
• All required fields present

---

🎓 What You Can Learn

1. Skill Structure (SKILL.md)

YAML Frontmatter:

---
name: debugging-kubernetes-incidents
description: Use when [trigger conditions]... [explanation]
---

Essential Sections:

• Overview (principles, abbreviations)
• When to Use (clear triggers)
• Quick Reference (tables)
• Common Confusions (✗/✓ examples)
• Decision Tree (Q&A navigation)
• Real-World Examples
• Keywords for Search

2. Documentation (README.md)

Key Elements:

• What the skill does
• When to use it
• Key features
• Example usage
• What makes it different
• Prerequisites
• Related skills

3. Testing (tests/scenarios.yaml)

Test Structure:

- name: test-identifier
  description: What you're testing
  prompt: "Realistic user query"
  model: haiku
  samples: 3
  expected:
    contains_keywords: [...]
  baseline_failure: What happens without skill

4. Marketplace Integration

Plugin Metadata:

• Name and description
• Source path (must start with ./)
• Version
• Author
• Tags and keywords

---

📋 Validation Steps

Before contributing, validate your skill:

1. Schema Validation

# If you have claudelint installed
claudelint debugging-kubernetes-incidents/SKILL.md

# Expected: No errors

2. Word Count

wc -w debugging-kubernetes-incidents/SKILL.md
# Technique skills: <1,000 words (this example: ~1,400)
# Reference skills: <1,500 words

3. Frontmatter Length

sed -n '/^---$/,/^---$/p' debugging-kubernetes-incidents/SKILL.md | wc -c
# Must be <1,024 characters

4. JSON Validation

python -m json.tool .claude-plugin/marketplace.json
# Expected: Valid JSON output

---

🔄 TDD for Documentation Process

This skill was created using Test-Driven Development for Documentation:

RED Phase (Failures)

1. Created 6 test scenarios
2. Ran tests WITHOUT the skill
3. Documented baseline failures:
   • Suggested fixes without investigation
   • Missed multi-source correlation
   • Confused symptoms with root causes

GREEN Phase (Minimal Skill)

1. Created SKILL.md addressing failures
2. Added investigation methodology
3. Included decision trees
4. All tests passed ✅

REFACTOR Phase (Improvement)

1. Enhanced examples
2. Improved decision trees
3. Added troubleshooting matrix
4. Refined methodology

---

🚀 Quick Start: Contributing to Konflux

Prerequisites

• GitHub account
• Git installed
• Python 3.8+ (for testing)
• Understanding of Kubernetes basics

Steps

1. Read CONTRIBUTION_GUIDE.md (comprehensive guide)
2. Fork Konflux skills repo: https://github.com/konflux-ci/skills
3. Copy this skill to your fork
4. Validate locally (schema, tests)
5. Create pull request
6. Respond to feedback

Estimated Time: 1-2 hours (including validation)

---

💡 Tips for Creating Your Own Skill

1. Start with Tests

Before writing skill content:

• Define 3-6 test scenarios
• Write realistic user prompts
• Document what should/shouldn't happen
• Run tests without skill (baseline failures)

2. Focus on Methodology

Skills should teach:

• How to think about the problem
• Systematic approaches to investigate
• Decision frameworks for choices
• Not just tool commands

3. Keep It Concise

• Technique skills: <1,000 words
• Use tables for structured data
• Move detailed info to README
• Every word should add value

4. Use Real Examples

• Base scenarios on actual incidents
• Include expected outputs
• Show before/after comparisons
• Make it practical

5. Test Thoroughly

• Run all test scenarios
• Validate schema
• Check word counts
• Get peer review

---

📚 Resources

Konflux Skills Repository

• Repo: https://github.com/konflux-ci/skills
• Guidelines: Read CLAUDE.md in the repo
• Examples: Study existing skills

Related Documentation

• Claude Code documentation
• Kubernetes debugging guides
• SRE best practices
• Incident response frameworks

This Example

• SKILL.md - The skill itself
• README.md - Skill documentation
• tests/ - Test suite
• CONTRIBUTION_GUIDE.md - How to contribute

---

🎯 Next Steps

1. Study this example thoroughly
2. Identify a skill need in your workflow
3. Create test scenarios first (TDD approach)
4. Write the skill addressing tests
5. Validate using provided guidelines
6. Contribute to Konflux repository

---

❓ FAQ

Q: Can I use this skill directly?

A: Yes! It's production-ready. You can:

• Use it in your own Claude Code setup
• Contribute it to Konflux repository
• Fork and customize it

Q: Is this skill Konflux-specific?

A: No. This is a general-purpose Kubernetes debugging skill that works with any Kubernetes cluster. It's suitable for the Konflux skills repository because it follows their format.

Q: What if my skill is longer than 1,000 words?

A:

• For technique skills: Must be <1,000 words (refactor to reduce)
• For reference skills: Can be <1,500 words
• Move detailed info to README.md
• Use tables to condense information

Q: Do all tests need to pass?

A: Yes. 100% test pass rate required before contribution. If tests fail:

• Update skill content to address failures
• Or refine test expectations if too strict

Q: How long does PR review take?

A: Varies. Typically:

• Initial review: 1-3 days
• Feedback iterations: 1-2 rounds
• Final approval: 1-2 days
• Total: 1-2 weeks average

---

🤝 Contributing

Found issues with this example? Have suggestions?

1. This is a test example in the SRE Copilot project
2. Create issues or PRs in the main project
3. Help improve this template for others

---

📄 License

Same as parent repository (Apache 2.0).

---

✨ Acknowledgments

• Gjorgji Georgievski (ggeorgie@redhat.com) - Author and maintainer
• SRE Copilot Team - For the original plugin content
• Konflux CI - For skills repository structure
• Claude Code - For making this possible

---

This example is ready for contribution to Konflux CI Skills repository! 🚀

Follow the CONTRIBUTION_GUIDE.md for step-by-step instructions.