zowe-agent-skills

A Zowe CLI plugin that generates Agent Skills definitions for all installed Zowe CLI commands, enabling AI agents to accurately invoke mainframe operations.

Quick Start

# Install the plugin
zowe plugins install zowe-agent-skills

# Generate skills globally (default: ~/.agents/skills)
zowe agent-skills generate

# Generate skills locally for the current project
zowe agent-skills generate --output-dir .agents/skills

# Only include specific groups
zowe agent-skills generate --include-only-groups zos-files zos-jobs

# Exclude groups you don't need
zowe agent-skills generate --exclude-groups db2 mq

# Ban groups — keeps the group visible with a single DO NOT USE directive instead of listing commands
zowe agent-skills generate --ban-groups db2

# Generate command index only — no syntax or examples files
zowe agent-skills generate --include-syntax false --include-examples false

# Full index for all groups, but syntax and examples only for zowe-debug
# (useful when the agent knows public commands but needs detail on a new or private plugin)
zowe agent-skills generate --syntax-groups zowe-debug --examples-groups zowe-debug

Design Philosophy

LLM agents are generally well-trained on publicly documented Zowe CLI commands and standard usage patterns. There may be trade-off equilibriums between adding enough skill content to improve usability versus adding too much content that consumes user's tokens and context window unnecessarily. There may also be CLI extensions installed that are site-specific and/or non-public. Skills tailored to the versions of what is actually installed may be preferable to a version agnostic skill content.

Instead, this plugin focuses on the gaps where agents are most likely to hallucinate or produce incorrect invocations:

• Version drift — reflecting the exact versions of Zowe CLI and installed plugins present in the environment, so agents don't assume capabilities from a different release
• Post-training changes — surfacing command syntax, options, or behaviors that changed after the model's training cutoff
• Private and undocumented extensions — capturing commands from internally developed or privately distributed plugins that the model has never seen
• Non-standard configurations — documenting locally configured profiles, connection aliases, or environment-specific defaults that affect how commands should be called

The goal is the smallest skill payload that maximizes invocation accuracy for the current usage context — and not to add the full API reference and examples into context.

Prerequisites

• Zowe CLI v8 or later (v3 release line)
• Node.js 18+
• npm 8+

Installation

zowe plugins install zowe-agent-skills

Or to install from source:

git clone https://github.com/jwflicker/zowe-agent-skills
cd zowe-agent-skills
npm install
npm run build
zowe plugins install .

Usage

Generate skill definitions

zowe agent-skills generate

Writes a single SKILL.md command index to ~/.agents/skills/zowe-cli/ by default. The index covers every installed command group and plugin, with one-line descriptions and invocation syntax. Meta groups (auth, config, daemon, plugins) and the zowe-agent-skills group itself are excluded.

The skill instructs the agent to run zowe <group> <command> --help or zowe <group> <command> --help-examples on demand for detailed syntax or worked examples — keeping the skill file lean while full detail remains available at runtime.

Options

| Option | Description | Default | |--------|-------------|---------| | --output-dir / -o | Directory to write skill files | ~/.agents/skills | | --include-syntax | Write per-group syntax reference files (syntax/<group>.md) | true | | --syntax-groups / -sg | Limit syntax files to specific groups; all groups still appear in SKILL.md | (all groups) | | --include-examples | Write per-group examples files (examples/<group>.md) | true | | --examples-groups / -eg | Limit examples files to specific groups; all groups still appear in SKILL.md | (all groups) | | --plugin / -p | Limit output to a specific plugin name | (all plugins) | | --exclude-groups / -e | Omit one or more groups from the skill entirely | (none) | | --ban-groups / -b | Include groups in the index but instruct the agent never to invoke them | (none) | | --include-only-groups / -i | Whitelist mode — only include the specified groups | (all groups) | | --overwrite | Overwrite existing skill files | false |

--include-only-groups is mutually exclusive with --exclude-groups and --ban-groups.

Examples

# Generate a skill covering all installed groups
zowe agent-skills generate

# Write skills to a project-local directory
zowe agent-skills generate --output-dir ./.agents/skills

# Only include zos-files and zos-jobs (run `zowe --help` to list installed groups)
zowe agent-skills generate --include-only-groups zos-files zos-jobs

# Exclude db2 and mq entirely
zowe agent-skills generate --exclude-groups db2 mq

# Keep db2 visible with a single DO NOT USE directive instead of listing its commands
zowe agent-skills generate --ban-groups db2

# Regenerate skills for one plugin after an update
zowe agent-skills generate --plugin @zowe/cics-for-zowe-cli --overwrite

# Use IBM RSE API plug-in as the primary interface for file and job operations —
# ban the core groups it supersedes so the agent uses RSE API commands instead
zowe plugins install @ibm/rse-api-for-zowe-cli
zowe agent-skills generate --ban-groups zos-files zos-jobs zos-ftp zos-ssh --overwrite

Skill Content

Each generated SKILL.md contains:

• A command index — one-line description and invocation syntax for every command in the included groups
• Links to syntax/ and examples/ files for each group (when those files are generated)
• Usage guidance instructing the agent when to load the per-group reference files and when to call --help on demand
• Ban annotations (when --ban-groups is used) — a DO NOT USE instruction in the usage guidance; banned groups receive no syntax or examples files

Output

Output lands under <output-dir>/zowe-cli/:

zowe-cli/
  SKILL.md          # command index with usage guidance and links
  syntax/
    <group>.md      # full option signatures for each group (--include-syntax)
  examples/
    <group>.md      # worked examples for each group (--include-examples)

When --syntax-groups or --examples-groups is used, only the named groups get per-group files; all other groups still appear in SKILL.md without links.

The examples/ directory in this repository contains committed output generated against a standard Zowe CLI install, kept in sync by a pre-commit hook.

Development

git config core.hooksPath .githooks   # activate pre-commit hook
npm install                            # install dependencies
npm run build                          # compile TypeScript
npm run test                           # run unit tests
npm run lint                           # lint source

The pre-commit hook rebuilds the project, reinstalls from local source, and regenerates examples/ before every commit to keep the committed example output in sync. See AGENTS.md for contributor notes.

Contributing

Issues and pull requests are welcome. This project follows the Zowe CLI contribution guidelines.

License

Apache 2.0