openstack-k8s-operators Operator Tools

Skills for openstack-k8s-operators development — debugging, testing, code review, feature planning, and plan execution. Supports Claude Code, Cursor, OpenCode, and Codex.

Installation

Claude Code (recommended)

Add the marketplace and install the plugin (two steps):

claude plugin marketplace add https://github.com/openstack-k8s-operators/devskills
claude plugin install openstack-k8s-agent-tools

To update to the latest version:

claude plugin update openstack-k8s-agent-tools@openstack-k8s-agent-tools

Cursor

Cursor reads Claude Code plugins from ~/.claude/plugins/cache/ automatically. If you have the Claude Code CLI installed, run the same marketplace commands:

claude plugin marketplace add https://github.com/openstack-k8s-operators/devskills
claude plugin install openstack-k8s-agent-tools

Restart Cursor after installing. Skills will appear in Cursor’s agent skill list and can be invoked from chat.

If you do not have the Claude Code CLI, clone the repo and use the manual install target instead:

git clone https://github.com/openstack-k8s-operators/devskills.git
cd openstack-k8s-agent-tools
make install-claude

This copies skills to ~/.claude/skills/ and agents to ~/.claude/agents/, which Cursor also discovers.

OpenCode

git clone https://github.com/openstack-k8s-operators/devskills.git
cd openstack-k8s-agent-tools
make install-opencode

Codex

Start Codex and ask its built-in skill installer to install this repository:

$skill-installer Install all skills from https://github.com/openstack-k8s-operators/devskills

Codex detects newly installed skills automatically. If they do not appear, restart Codex. Run /skills or type $ in the prompt to select a skill.

For example, select openstack-k8s-agent-tools:code-review, then provide its arguments:

$openstack-k8s-agent-tools:code-review 438

To use a skill in codex, use $, not /. For example:

› /jira OSPRH-35190

• Unrecognized command '/jira'. Type "/" for a list of supported commands.

› $jira OSPRH-35190

• I’m using the Jira skill to inspect OSPRH-35190 and validate its hierarchy. I’ll make no Jira changes.

Manual install (Claude Code, without marketplace)

make install-claude

Dependencies

Skills

The table uses Claude Code’s /skill-name notation. In Codex, run /skills or type $ and select the corresponding openstack-k8s-agent-tools skill.

Skills with an agent load an AGENT.md file that contains the full domain knowledge and methodology. Skills without an agent are self-contained in their SKILL.md.

Skill Architecture

This plugin uses two patterns for skills. Choosing the right one up front avoids rework later.

Self-contained – all logic lives in SKILL.md. Good for straightforward workflows that don’t need deep domain knowledge (e.g., skills/code-style/SKILL.md).

Agent-backed – SKILL.md handles input routing and orchestration, then dispatches an AGENT.md that holds the domain methodology. Use this when the skill needs complex evaluation criteria, multi-step analysis, or reusable expertise that benefits from isolated context (e.g., skills/code-review/SKILL.md + agents/code-review/AGENT.md). Note that the parent conversation only receives the agent’s summary, so detailed intermediate findings stay in the sub-agent’s context. If follow-up discussion on the full analysis is expected, consider keeping the logic self-contained. The dispatch looks like:

Agent(subagent_type="openstack-k8s-agent-tools::", ...)

OpenCode users: write skills using the Claude Code dispatch syntax above. make install-opencode automatically converts it to the @name mention form that OpenCode expects.

When scaffolding an agent-backed skill, run both make new-skill and make new-agent, and add "Agent" to the skill’s allowed-tools list.

See the Development Guide for the full architecture walkthrough, flow diagrams, and AGENT.md frontmatter reference.

Quickstart

Create a new skill or agent

# Scaffold a new skill
make new-skill my-skill

# Scaffold a new agent
make new-agent my-agent

# Validate structure
make validate

See the DEVELOPMENT guide for more details on extending the plugin.

For usage examples, workflows, and skill reference, see the GETTING-STARTED guide.

Evals

Behavioral testing for skills using promptfoo with the claude-agent-sdk provider. Each skill has a self-contained eval directory with prompt templates, Go fixtures, and score-based Python graders.

make eval-setup                      # install dependencies (one-time)
make eval EVAL_SKILL=code-review     # run evals for one skill
make eval                            # run all evals
make new-eval my-skill               # scaffold eval for a new skill

See the Evals README for framework details, test tiers, grader conventions, and per-skill documentation.

Documentation

• Getting Started — usage examples, workflows, and skill reference
• MCP Setup — Atlassian MCP configuration for Jira integration
• Development Guide — extending the plugin with new skills
• Feature Planning — detailed walkthrough with use case
• Memory and State — shared memory, state tracking, worktrees, dependencies
• AGENTS.md — project conventions for AI agents

Roadmap

• [x] install.sh — manual installation script with platform support (Claude Code, OpenCode)
• [x] Code review accepts PR number, branch, or specific files
• [x] Shared memory (MEMORY.md), state tracking (state.json), worktree isolation, dependency resolution
• [x] /analyze-must-gather — must-gather archive analysis
• [x] /bug — bug fix planning alias
• [x] make new-skill / make new-agent — scaffold new skills and agents
• [ ] Guidelines on sandboxing
• [ ] Jira sub-task export from task breakdowns
• [ ] Plan diffing (detect Jira ticket changes after plan creation)

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.