epic: Agent Skills — built-in operational skills, authoring guide, registry distribution

[joshrotenberg]

Overview

Adopt the Agent Skills specification for extensible, portable operational workflows that compose redisctl's MCP tools. Ship built-in skills for common Enterprise and Cloud operations, provide an authoring guide for custom skills, and distribute via skillet registries.

This replaces the earlier approach of building a bespoke runtime-loaded-prompts system (#644) and hardcoded MCP prompts (#712). Skills are the better path because they're portable across agents (Claude Code, Cursor, Gemini CLI, etc.), require no Rust code changes, and have a standard distribution story via skillet.

Goals

• Ship built-in operational skills that compose redisctl MCP tools
• Provide a skill authoring guide so users can create custom workflows
• Publish skills to a skillet registry for easy discovery and installation
• Cover the most common Enterprise and Cloud operational scenarios

Sub-Issues

Built-in Enterprise Skills

• pre-upgrade-health-check — verify cluster readiness before upgrade (get_cluster, list_nodes, get_license, list_alerts, get_database_stats)
• cluster-capacity-planning — assess capacity and recommend scaling (get_all_nodes_stats, get_all_databases_stats, get_all_shards_stats, get_cluster_stats)
• cluster-troubleshooting — diagnose reported issues via triage workflow (get_cluster, list_alerts, list_nodes, list_logs, get_database_stats, get_database_endpoints)
• database-performance-analysis — analyze database performance bottlenecks (get_database_stats, get_shard_stats, list_shards, list_database_alerts)

Built-in Cloud Skills

• cloud-database-provisioning — guide through creating a subscription and database with best practices
• cloud-migration-planning — plan migration between environments using Cloud API tools

Infrastructure

• Determine where skills live in the repo (skills/ at root? crates/redisctl-mcp/skills/?)
• Skill authoring guide — document available tools, patterns for multi-profile operations, examples
• Publish skills to a skillet registry
• Add installation instructions to docs (manual copy, skillet install, etc.)

Skill Format

Each skill follows the Agent Skills specification:

skills/
  pre-upgrade-health-check/
    SKILL.md
  cluster-capacity-planning/
    SKILL.md
    references/
      thresholds.md       # Memory/CPU warning thresholds, scaling heuristics
  cluster-troubleshooting/
    SKILL.md
  database-performance-analysis/
    SKILL.md

Example SKILL.md:

---
name: pre-upgrade-health-check
description: >
  Verify a Redis Enterprise cluster is ready for upgrade by checking
  node health, license status, alerts, and database backup state.
  Use when planning a cluster upgrade or maintenance window.
compatibility: Requires redisctl MCP server with enterprise tools enabled
metadata:
  author: redis-developer
  version: "1.0"
---

# Pre-Upgrade Health Check

## When to use
Use this skill before any planned Redis Enterprise cluster upgrade
or maintenance window...

## Steps
1. Check cluster status and version with `get_cluster`
2. Verify all nodes are healthy with `list_nodes` and `get_node`
3. Check license expiry with `get_license` and usage with `get_license_usage`
4. Review active alerts with `list_alerts`
5. Verify database health and backup recency with `list_databases` / `get_database_stats`

## Decision criteria
- **Block upgrade** if: any node unhealthy, license expires within 7 days, critical alerts active, any database backup older than 24 hours
- **Warn** if: license expires within 30 days, non-critical alerts active, memory utilization > 80%
- **Clear** if: all checks pass

## Output
Provide a go/no-go summary table with each check's status and details.

Distribution

1. Shipped in repo: skills live under skills/ and can be copied to agent skill directories
2. Skillet registry: skillet install redis/pre-upgrade-health-check
3. Docs: installation instructions for each supported agent

What stays the same

The existing hardcoded MCP prompts in prompts.rs (troubleshoot, performance, capacity planning, migration) remain as-is. They serve a complementary purpose via the MCP prompts/list protocol for clients that support it.

References

• Agent Skills specification: https://agentskills.io/specification
• Example skills: https://github.com/anthropics/skills
• Skillet (skill registry toolkit): https://github.com/joshrotenberg/grimoire
• Previous: feat(mcp): ship built-in Agent Skills and skill authoring guide #644 (superseded), feat(mcp): create enterprise operational Agent Skills #712 (superseded)
• Enterprise epic: epic: Enterprise — operational workflows, cluster health, coverage #679 (closed)