Create Your Own Skills & Plugins

From idea to marketplace in 5 phases
ℹ️
Who this is for: RHDP team members who want to automate a workflow as a reusable Claude Code skill. You don't write skills by hand -- you use Claude to help you build them step by step.

The Real Workflow

Creating a skill is a 5-phase process. Each phase builds on the previous one:

Phase What You Do What You Get
1. Document Have Claude interview you about your manual process Plain .md reference files capturing your workflow
2. Convert Point Claude at your .md files + an existing RHDP skill A working SKILL.md
3. Package Create the plugin directory structure A plugin ready for testing
4. Test Install locally and run through your workflow A validated, working skill
5. Publish Push to a marketplace repo Your team can install it
✅
Key insight: Most people skip Phase 1 and jump straight to writing a SKILL.md. This fails because you can't articulate every step, edge case, and decision in a single prompt. The iterative documentation phase is where the real value creation happens.

Phase 1: Document Your Workflow with Claude

Before writing any skill, get your process out of your head and into written form. Claude is your interviewer.

Start a conversation

Open Claude Code in your project directory and describe what you want to automate:

I want to automate the process of [creating new catalog items / deploying workshops /
validating content / whatever you do manually].

Here's what I currently do:
1. [First thing]
2. [Second thing]
3. [Third thing]

Can you help me document this process? Ask me questions about each step
so we capture everything -- prerequisites, decisions, edge cases, and outputs.

Build reference files iteratively

As Claude interviews you, ask it to write up each part as a separate .md file:

Great, now write up what we've discussed about the prerequisites
as docs/my-workflow/01-prerequisites.md

Then write the deployment steps as docs/my-workflow/02-deployment.md

And the validation checks as docs/my-workflow/03-validation.md

What your reference files should capture

Each .md file should cover:

⚠️
Don't rush this step. If you already have documentation, runbooks, shell scripts, or team wiki pages, point Claude at those instead: "Read docs/deployment-process.md and help me restructure it as step-by-step reference files."

Phase 2: Convert Your Docs into a SKILL.md

Now that you have reference files, point Claude at them along with an existing RHDP skill as a template.

The conversion prompt

Read my reference files:
- docs/my-workflow/01-prerequisites.md
- docs/my-workflow/02-deployment.md
- docs/my-workflow/03-validation.md

Also read this existing RHDP skill for patterns:
agnosticv/skills/catalog-builder/SKILL.md

Create a SKILL.md for my workflow in skills/my-skill/SKILL.md

Follow the same patterns:
- Two YAML frontmatter blocks (identity + execution context)
- "What You'll Need Before Starting" section
- "When to Use / Don't Use" section
- Numbered workflow steps (Step 1, Step 2, etc.)
- Ask questions SEQUENTIALLY -- one at a time, wait for answer
- Use bash commands for file operations
- Show output confirmations, not full file content

What Claude will create

Claude generates a SKILL.md with this structure:

---
name: my-plugin:my-skill
description: What this skill does in one sentence
---

---
context: main
model: claude-opus-4-6
---

# My Skill Title

One-line description.

## What You'll Need Before Starting

**Required:**
- Item 1
- Item 2

**Helpful to have:**
- Item 3

## When to Use

**Use this skill when you want to:**
- Use case 1
- Use case 2

**Don't use this for:**
- Wrong use case -> use `/other-skill`

## Workflow

### Step 1: Detect Environment
[Commands to check prerequisites]

### Step 2: Ask Questions
[Sequential questions with defaults]

### Step 3: Generate Output
[File creation steps]

### Step 4: Validate and Deliver
[Verification commands and summary]

Understanding the frontmatter

Every SKILL.md has two YAML blocks separated by ---:

Block 1 – Identity (required):

Field Purpose Example
name Invocation name, format: namespace:skill-name showroom:create-lab
description One-line description shown in /skills list Free text

Block 2 – Execution context (optional):

Field Purpose Values
context How the skill runs main (shares conversation), fork (isolated thread)
model Which Claude model to use claude-opus-4-6, sonnet, haiku
✅
When to use context: fork: Use it for validation or analysis tasks that should not pollute the main conversation. The verify-content skill uses this. For skills that create files or need ongoing conversation context, use context: main.

Iterate with Claude

Your first version won’t be perfect. Iterate:

This is good! Can you add:
1. Validation that the target directory exists before starting
2. A confirmation step before writing files
3. Error handling if the git command fails

What happens if:
- The user cancels midway?
- The config file doesn't exist?
- The branch already exists?
Can you add error handling for these cases?

Can you improve the UX by:
- Adding a summary at the end showing what was created
- Making the git workflow optional
- Adding a dry-run mode

Which RHDP skills to use as templates

If your skill does… Study this skill Why
File generation agnosticv:catalog-builder Multi-mode, templates, YAML generation
Content creation showroom:create-lab Sequential questions, AsciiDoc output, reference repo pattern
Content transformation showroom:blog-generate Read input -> transform -> write output
Validation showroom:verify-content Fork context, verification prompts, reporting
Infrastructure health:deployment-validator Ansible role generation, test creation

Phase 3: Create the Plugin Structure

A plugin packages your skill(s) for distribution. The minimum structure is two files.

Minimum viable plugin

my-plugin/
  .claude-plugin/
    plugin.json        # Plugin metadata (REQUIRED)
  skills/
    my-skill/
      SKILL.md         # Your skill (REQUIRED)

Create plugin.json

Here is the actual showroom/.claude-plugin/plugin.json from the RHDP marketplace – it’s 7 lines:

{
  "name": "showroom",
  "version": "1.0.0",
  "description": "Workshop and demo authoring tools",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  }
}
Field Required Purpose
name Yes Plugin name; becomes the namespace prefix (e.g., showroom:create-lab)
version Yes Semver version; shown in /plugin list
description Yes Description shown in marketplace listings
author No Your contact info
⚠️
Critical: The name in plugin.json becomes the namespace prefix for all your skills. If your plugin name is my-tools and your skill name is deploy, users will invoke it as /my-tools:deploy.

Ask Claude to do it

You don’t need to create this by hand:

Create a plugin.json for my skill.
Plugin name: my-tools
Description: Deployment automation for my team
Put it in .claude-plugin/plugin.json

Optional directories

As your plugin grows, you can add optional directories:

my-plugin/
  .claude-plugin/
    plugin.json
  skills/
    skill-one/
      SKILL.md
    skill-two/
      SKILL.md
  agents/             # Specialized AI personas your skills can invoke
    reviewer.md
  docs/               # Shared documentation referenced by skills
    COMMON-RULES.md
  prompts/            # Verification/validation prompt files
    check-quality.txt
  templates/          # Content templates for file generation
    config.yaml
  README.md
Directory Purpose Real example
agents/ AI personas with specific expertise (editor, reviewer, style checker) showroom/agents/style-enforcer.md
docs/ Shared rules and reference docs that multiple skills use showroom/docs/SKILL-COMMON-RULES.md
prompts/ Validation criteria files read before generating content showroom/prompts/redhat_style_guide_validation.txt
templates/ Starter templates for file generation showroom/templates/workshop/

Phase 4: Test Locally

Install your plugin

# Option 1: Install from local directory
/plugin marketplace add /path/to/your/plugin-directory

# Option 2: Install from GitHub
/plugin marketplace add yourusername/my-plugin-repo

Then install:

/plugin install my-tools@my-marketplace

Verify it loaded

# Check plugin is listed
/plugin list

# Check skill appears
# Your skill should show as my-tools:skill-name

Run through the workflow

# Navigate to a test project
cd ~/test-project

# Run your skill
/my-tools:deploy

Fix issues with Claude

When something doesn’t work, tell Claude exactly what went wrong:

My skill failed at Step 3. The error was:
[paste error message]

Can you fix the SKILL.md? The issue is that it tries to read
a file that doesn't exist yet at that step.

Testing checklist

Phase 5: Publish

Option A: Standalone GitHub repo

Push your plugin to a GitHub repository. Anyone can install it:

# Initialize and push
cd my-plugin/
git init && git add . && git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/my-plugin.git
git push -u origin main

Users install with:

/plugin marketplace add yourusername/my-plugin
/plugin install my-tools@my-plugin

Option B: Contribute to RHDP marketplace

If your skill is useful for the wider RHDP team:

  1. Fork the marketplace: 
    git clone https://github.com/rhpds/rhdp-skills-marketplace
cd rhdp-skills-marketplace

  2. Create your plugin directory following the structure in Phase 3

  3. Submit a pull request – requires CODEOWNERS approval
ℹ️
RHDP marketplace users install with:
/plugin marketplace add rhpds/rhdp-skills-marketplace
/plugin install my-tools@rhdp-marketplace

Reference: Patterns from Real Skills

These patterns appear in every well-built RHDP skill. Use them in yours.

Pattern 1: Sequential questions

Ask one question at a time. Wait for the answer before asking the next one.

### Step 2: Ask Questions

1. **Project name**
   - Ask: "What is the project name?"
   - Default: [detected from git repo]
   - WAIT for answer before proceeding

2. **Target environment**
   - Ask: "Which environment? (dev/stage/prod)"
   - Default: dev
   - WAIT for answer before proceeding

Pattern 2: Detect first, ask second

Try to auto-detect information before asking the user:

### Step 1: Detect Environment

1. Check if in git repository:
   ```bash
   git rev-parse --show-toplevel 2>/dev/null
  1. If git repo found:
    • Use detected repo name as default
    • Show to user for confirmation
  2. If not in git repo:
    • Ask user for project name
    • Ask for repository URL ```

Pattern 3: Write files, don’t display them

### Step 5: Generate Output

Use the Write tool to create files. Show brief confirmations only:

"Created: config/deployment.yaml (45 lines)"
"Created: config/service.yaml (22 lines)"

Do NOT display full file content in the conversation.

Pattern 4: Failure mode behavior

**If [command] fails:**

**Cannot proceed safely**

**Blocking issue**: [specific problem]

**What I need**:
1. [specific fix 1]
2. [specific fix 2]

**Or**: Would you like to proceed with [fallback option]?

Pattern 5: Cross-skill references

**Don't use this for:**
- Creating workshop content -> use `/showroom:create-lab`
- Validating configurations -> use `/agnosticv:validator`

Reference: RHDP Skills to Learn From

All of these are in the RHDP marketplace repo:

Skill Path What to learn from it
Create Lab showroom/skills/create-lab/SKILL.md Sequential questions, reference repo pattern, AsciiDoc generation
Create Demo showroom/skills/create-demo/SKILL.md Know/Show structure, presenter-led content
Blog Generate showroom/skills/blog-generate/SKILL.md Content transformation, platform-specific output
Verify Content showroom/skills/verify-content/SKILL.md Fork context, verification prompts, multi-agent validation
Catalog Builder agnosticv/skills/catalog-builder/SKILL.md Multi-mode operation, YAML templates, git workflow
Validator agnosticv/skills/validator/SKILL.md Validation rules, error reporting
Deployment Validator health/skills/deployment-validator/SKILL.md Ansible role generation, test creation

Prompting Tips

Be specific about structure

# Bad
Create a skill for deployments

# Good
Create a skill that validates prerequisites (oc logged in, project exists),
asks for environment (dev/stage/prod), deploys with oc apply, and shows status.
Use agnosticv:catalog-builder as a template for the step structure.

Reference specific skills

# Bad
Make it work like other skills

# Good
Use the question pattern from showroom:create-lab Step 2,
and the file generation pattern from agnosticv:catalog-builder Step 10

Specify what to keep and what to change

# Bad
Similar to catalog-builder but different

# Good
Keep: step structure, git workflow, confirmation prompts
Change: Instead of YAML files, generate JSON configs.
Instead of AgnosticV paths, detect Terraform directories.

Iterate incrementally

# Bad
Add 10 new features all at once

# Good
First add prerequisite validation. Let me test that.
Then we'll add confirmation prompts. Then error handling.

Resources

RHDP Marketplace

Source code with all skills and plugins

Claude Code Best Practices

CLAUDE.md setup, models, context, sessions

Quick Reference

Commands, shortcuts, workflows at a glance

Claude Code Setup

First-time installation guide

Community:

Back to Home