crossplane-debug

Debug Crossplane compositions, functions (KCL, Go templates, patch-and-transform, auto-ready), and managed resources - a skill for AI coding agents.

Features

• Debug composition rendering issues with crossplane beta render
• Extract compositions from remote clusters for local debugging
• Troubleshoot function execution (KCL, Go templates, patch-and-transform)
• Diagnose resource creation failures and dependency problems
• Trace claim/XR status and managed resource conditions
• Common error patterns and solutions reference

Installation

npx skills add kanzifucius/crossplane-debug

You'll be prompted to select which AI agents to install to.

Install to specific agents

npx skills add kanzifucius/crossplane-debug -a claude-code -a opencode

Supported Agents

This skill works with 40+ AI coding agents including:

• OpenCode
• Claude Code
• Cursor
• Codex
• GitHub Copilot
• Windsurf
• And many more...

See the full list at skills.sh.

Usage

After installation, the skill is automatically triggered when working with Crossplane resources. Keywords that activate the skill:

• "crossplane"
• "composition"
• "XR" / "composite resource"
• "claim"
• "function-kcl"
• "managed resource"

Example Prompts

"Debug why my XR isn't creating resources"
"Help me troubleshoot this Crossplane composition"
"The function-kcl step is failing, can you help?"
"Extract the composition from my cluster for local debugging"

Manual Extraction Script

The skill includes a helper script for extracting compositions from remote clusters:

# After installation, find the script in your agent's skill directory
./scripts/extract-composition.sh <composition-name> [xr-kind] [xr-name]

# Examples:
./scripts/extract-composition.sh my-database-composition
./scripts/extract-composition.sh my-app-composition XMyApp my-app-instance

This creates a debug-<composition-name>/ directory with all files needed for crossplane beta render.

What's Included

skills/crossplane-debug/
├── SKILL.md                      # Main skill instructions
├── scripts/
│   └── extract-composition.sh    # Cluster extraction helper
└── references/
    ├── common-errors.md          # Error patterns and solutions
    └── kcl-patterns.md           # KCL syntax patterns for compositions

Debugging Workflow

The skill guides you through a systematic debugging approach:

Issue reported
    |
    v
Do you have composition files locally?
    |
    +--NO--> Extract from cluster first
    |        Run: scripts/extract-composition.sh
    |
    +--YES--> Is the composition rendering correctly?
                 |
                 +--NO--> Run `crossplane beta render` locally
                 |
                 +--YES--> Are resources being created?
                              |
                              +--NO--> Check XR/Claim status
                              |        Run `crossplane beta trace`
                              |
                              +--YES--> Are resources Ready?
                                           |
                                           +--NO--> Check managed resource conditions
                                           |
                                           +--YES--> Issue is external to Crossplane

Requirements

• kubectl (for cluster debugging)
• crossplane CLI (for beta render and beta trace)

License

MIT

Links

• GitHub Repository
• skills.sh - Universal skills manager
• Crossplane Documentation