sosreport

A collection of Claude Code plugins to automate and assist with various development tasks.

Discover available plugins

Installation

From the Claude Code Plugin Marketplace

1. Add the marketplace:

``bash /plugin marketplace add openshift-eng/ai-helpers ``

1. Install a plugin:

``bash /plugin install jira@ai-helpers ``

1. Use the commands:

``bash /jira:solve OCPBUGS-12345 origin ``

Updating Plugins

To get the latest plugin versions:

1. Update the marketplace (fetches latest plugin catalog):

``bash /plugin marketplace update ai-helpers ``

1. Reinstall the plugin (downloads new version):

``bash /plugin install <plugin>@ai-helpers ``

Automatic Catalog Sync

Add a SessionStart hook to automatically sync the marketplace catalog on each session. In your project's .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "command": "claude plugin marketplace update ai-helpers",
        "timeout": 30000
      }
    ]
  }
}

Note: This only refreshes the catalog (what's available). To actually update an installed plugin to a newer version, you still need to reinstall it with /plugin install <plugin>@ai-helpers.

Using Cursor

Cursor is able to find the various commands defined in this repo by making it available inside your ~/.cursor/commands directory.

$ mkdir -p ~/.cursor/commands
$ git clone [email protected]:openshift-eng/ai-helpers.git
$ ln -s ai-helpers ~/.cursor/commands/ai-helpers

Using the Docker Container

A container is available with Claude Code and all plugins pre-installed.

Building the Container

podman build -f images/Dockerfile -t ai-helpers .

Running with Vertex AI and gcloud Authentication

To use Claude Code with Google Cloud's Vertex AI, you need to pass through your gcloud credentials and set the required environment variables:

podman run -it \
  -e CLAUDE_CODE_USE_VERTEX=1 \
  -e CLOUD_ML_REGION=your-ml-region \
  -e ANTHROPIC_VERTEX_PROJECT_ID=your-project-id \
  -v ~/.config/gcloud:/home/claude/.config/gcloud:ro \
  -v $(pwd):/workspace \
  -w /workspace \
  ai-helpers

Environment Variables:

• •CLAUDE_CODE_USE_VERTEX=1 - Enable Vertex AI integration
• •CLOUD_ML_REGION - Your GCP region (e.g., us-east5)
• •ANTHROPIC_VERTEX_PROJECT_ID - Your GCP project ID

Volume Mounts:

• •-v ~/.config/gcloud:/home/claude/.config/gcloud:ro - Passes through your gcloud authentication (read-only)
• •-v $(pwd):/workspace - Mounts your current directory into the container

Running Commands Non-Interactively

You can execute Claude Code commands directly without entering an interactive session using the -p or --print flag:

podman run -it \
  -e CLAUDE_CODE_USE_VERTEX=1 \
  -e CLOUD_ML_REGION=your-ml-region \
  -e ANTHROPIC_VERTEX_PROJECT_ID=your-project-id \
  -v ~/.config/gcloud:/home/claude/.config/gcloud:ro \
  -v $(pwd):/workspace \
  -w /workspace \
  ai-helpers \
  --print "/hello-world:echo Hello from Claude Code!"

This will:

1. Start the container with your gcloud credentials
2. Execute the /hello-world:echo command with the provided message
3. Print the response and exit when complete

Available Plugins

For a complete list of all available plugins and commands, see the [AI Helpers Marketplace](https://openshift-eng.github.io/ai-helpers/).

Plugin Development

Want to contribute or create your own plugins? Check out the plugins/ directory for examples. Make sure your commands and agents follow the conventions for the Sections structure presented in the hello-world reference implementation plugin (see `hello-world:echo` for an example).

Ethical Guidelines

Plugins, commands, skills, and hooks must NEVER reference real people by name, even as stylistic examples (e.g., "in the style of <specific human>").

Ethical rationale:

1. Consent: Individuals have not consented to have their identity or persona used in AI-generated content
2. Misrepresentation: AI cannot accurately replicate a person's unique voice, style, or intent
3. Intellectual Property: A person's distinctive style may be protected
4. Dignity: Using someone's identity without permission diminishes their autonomy

Instead, describe specific qualities explicitly

Good examples:

• •"Write commit messages that are direct, technically precise, and focused on the rationale behind changes"
• •"Explain using clear analogies, a sense of wonder, and accessible language for non-experts"
• •"Code review comments that are encouraging, constructive, and focus on collaborative improvement"

When you identify a desirable characteristic (clarity, brevity, formality, humor, etc.), describe it explicitly rather than using a person as proxy.

Adding New Commands

Check for overlaps first - Before coding, validate your idea:

/utils:review-ai-helpers-overlap --idea "brief description of your command"

Collaborating on existing work instead of duplicating parallel efforts is always encouraged when overlap is found. This helps maintain a clean, non-redundant plugin collection in such an actively developed project (see `/utils:review-ai-helpers-overlap` for detailed usage).

When contributing new commands:

1. If your command fits an existing plugin: Add it to the appropriate plugin's commands/ directory
2. If your command doesn't have a clear parent plugin: Add it to the utils plugin (plugins/utils/commands/)

- The utils plugin serves as a catch-all for commands that don't fit existing categories - Once we accumulate several related commands in utils, they can be segregated into a new targeted plugin

Creating a New Plugin

If you're contributing several related commands that warrant their own plugin:

1. Create a new directory under plugins/ with your plugin name
2. Create the plugin structure:

`` plugins/your-plugin/ ├── .claude-plugin/ │ └── plugin.json └── commands/ └── your-command.md ``

1. Register your plugin in .claude-plugin/marketplace.json

Validating Plugins

This repository uses skillsaw to validate plugin structure:

make lint

Additional Documentation

• •[AI Helpers Marketplace](https://openshift-eng.github.io/ai-helpers/) - Complete list of all available plugins and commands
• •[CONTRIBUTING.md](CONTRIBUTING.md) - Guidelines for contributing plugins, including versioning policy
• •[AGENTS.md](AGENTS.md) - Complete guide for AI agents working with this repository
• •[CLAUDE.md](CLAUDE.md) - Claude-specific configuration and notes

License

See LICENSE for details.