feat: add AGENTS.md and CLI agent skills

AGENTS.md

@@ -0,0 +1,144 @@
+# AGENTS.md
+
+Context and instructions for AI coding agents working on the redisctl project.
+
+## Project Overview
+
+redisctl is a Rust workspace with three crates that share a lockstep version (currently 0.9.1):
+
+| Crate | Path | Purpose |
+|-------|------|---------|
+| **redisctl-core** | `crates/redisctl-core/` | Shared library: config/profile management, Cloud and Enterprise API clients, error handling |
+| **redisctl** | `crates/redisctl/` | CLI binary: commands, workflows, connection management |
+| **redisctl-mcp** | `crates/redisctl-mcp/` | MCP server for AI agents: ~371 tools, policy engine, skills system |
+
+## Build and Test
+
+```bash
+# Format (required before push)
+cargo fmt --all
+
+# Lint (all warnings are errors in CI)
+cargo clippy --all-targets --all-features -- -D warnings
+
+# Unit tests
+cargo test --workspace
+
+# Integration tests (requires Docker for Redis)
+cargo test --workspace --test '*' --all-features
+
+# Reuse Docker containers across test runs
+REUSE_CONTAINERS=1 cargo test --workspace --test '*' --all-features
+```
+
+**Always run fmt + clippy before pushing.** CI will reject unformatted code or clippy warnings.
+
+## CI Checks
+
+PRs must pass:
+1. `cargo fmt --all -- --check`
+2. `cargo clippy --all-targets --all-features -- -D warnings`
+3. Unit tests per crate (parallel)
+4. Integration tests
+5. Platform builds (Linux required; macOS and Windows are optional)
+
+## Crate Architecture
+
+### Feature Flags
+
+**redisctl** (CLI):
+- `default = ["full", "secure-storage"]`
+- `full = ["cloud", "enterprise", "upload"]`
+- `secure-storage` enables keyring-based credential storage
+
+**redisctl-mcp** (MCP server):
+- `default = ["http", "cloud", "enterprise", "database"]`
+- Each toolset (`cloud`, `enterprise`, `database`) can be compiled independently
+
+### Key Patterns
+
+**database_tool! macro** (`crates/redisctl-mcp/src/tools/macros.rs`):
+Generates MCP tool structs with safety annotations. Three safety tiers:
+- `database_tool!(read_only, ...)` -- no side effects
+- `database_tool!(write, ...)` -- creates or modifies data
+- `database_tool!(destructive, ...)` -- irreversible operations
+
+Field attributes like `#[serde(...)]` pass through the macro. Numeric parameters that might arrive as strings from MCP clients use custom deserializers from `serde_helpers.rs`.
+
+**mcp_module! macro**: Generates `TOOL_NAMES` constant and `router()` function for each tool sub-module.
+
+**Policy system** (`crates/redisctl-mcp/src/policy.rs`): TOML-based policy engine with three safety tiers (ReadOnly, ReadWrite, Full), per-toolset overrides, and allow/deny lists.
+
+**Profile system** (`crates/redisctl-core/`): TOML config at `~/.config/redisctl/config.toml` with profiles for Cloud, Enterprise, and direct Redis connections. Supports env var substitution.
+
+### Module Organization
+
+MCP tools are organized into toolsets with sub-modules:
+```
+tools/
+  redis/          # ~125 tools: server, keys, structures, json, search, diagnostics, bulk
+  cloud/          # ~147 tools: subscriptions, account, networking, fixed
+  enterprise/     # ~91 tools: cluster, databases, rbac, observability, proxy, services
+  profile.rs      # 8 tools: profile management
+```
+
+CLI commands mirror this structure:
+```
+cli/
+  cloud.rs        # Cloud subcommands
+  enterprise.rs   # Enterprise subcommands
+  mod.rs          # Top-level command tree
+```
+
+## Conventions
+
+### Commits
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+- `feat:` new feature (minor version bump)
+- `fix:` bug fix (patch bump)
+- `docs:` documentation only
+- `refactor:` no behavior change
+- `test:` test additions or fixes
+- `chore:` maintenance
+
+Scope by crate when relevant: `feat(mcp):`, `fix(core):`, `docs(cli):`.
+
+### Code Style
+
+- Rust edition 2024, MSRV 1.90+
+- No `unwrap()` in production code -- use proper error handling
+- Prefer `anyhow` for CLI errors, `tower_mcp::Error` for MCP tool errors
+- Tool descriptions are the primary documentation for MCP tools -- keep them accurate and concise
+
+### PRs
+
+- Use feature branches (`feat/`, `fix/`, `docs/`)
+- Open Draft PRs early
+- Squash and merge to main
+- Versions are bumped automatically by release-plz based on commit types
+
+## Dependencies
+
+API client crates are external git dependencies on the `main` branch:
+- `redis-cloud` from `github.com/redis-developer/redis-cloud-rs`
+- `redis-enterprise` from `github.com/redis-developer/redis-enterprise-rs`
+
+These are published separately and versioned independently.
+
+## MCP Skills
+
+Skills are workflow templates in `crates/redisctl-mcp/skills/` following the [agentskills.io spec](https://agentskills.io/specification):
+
+```
+skills/
+  index-advisor/SKILL.md      # Recommend search index schemas
+  query-tuning/SKILL.md       # Optimize queries with FT.EXPLAIN/FT.PROFILE
+  index-ab-test/SKILL.md      # Compare multiple index configurations
+```
+
+Each SKILL.md has YAML frontmatter (`name`, `description`) and a markdown body with step-by-step instructions that reference MCP tools.
+
+## License
+
+MIT OR Apache-2.0

skills/redisctl-cloud-management/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: redisctl-cloud-management
+description: Manage Redis Cloud subscriptions, databases, and resources via the redisctl CLI. Use when provisioning, updating, or monitoring Redis Cloud infrastructure.
+---
+
+## Overview
+
+Manage the full lifecycle of Redis Cloud resources: subscriptions, databases, users, ACLs, and tasks.
+
+## Subscriptions
+
+```bash
+# List all subscriptions
+redisctl cloud subscription list
+
+# Get subscription details
+redisctl cloud subscription get --id 12345
+
+# Create a subscription (JSON input)
+redisctl cloud subscription create --data '{...}'
+
+# Update a subscription
+redisctl cloud subscription update --id 12345 --data '{...}'
+
+# Delete a subscription
+redisctl cloud subscription delete --id 12345
+```
+
+## Databases
+
+```bash
+# List databases in a subscription
+redisctl cloud database list --subscription-id 12345
+
+# Get database details
+redisctl cloud database get --subscription-id 12345 --id 67890
+
+# Create a database
+redisctl cloud database create --subscription-id 12345 --data '{...}'
+
+# Update a database
+redisctl cloud database update --subscription-id 12345 --id 67890 --data '{...}'
+
+# Delete a database
+redisctl cloud database delete --subscription-id 12345 --id 67890
+
+# Pause/recover a database
+redisctl cloud database pause --subscription-id 12345 --id 67890
+redisctl cloud database recover --subscription-id 12345 --id 67890
+
+# Backup a database
+redisctl cloud database backup --subscription-id 12345 --id 67890
+```
+
+## Essentials / Fixed Tier
+
+For smaller, fixed-price databases:
+
+```bash
+redisctl cloud fixed-subscription list
+redisctl cloud fixed-database list --subscription-id 12345
+redisctl cloud fixed-database create --subscription-id 12345 --data '{...}'
+```
+
+## Task Tracking
+
+Cloud operations are async. Track tasks:
+
+```bash
+# List recent tasks
+redisctl cloud task list
+
+# Get task status
+redisctl cloud task get --id <task-id>
+
+# Wait for a task to complete
+redisctl cloud task wait --id <task-id>
+```
+
+## Workflows
+
+Multi-step operations:
+
+```bash
+# Complete subscription setup with optional database
+redisctl cloud workflow subscription-setup
+```
+
+## Cost Reports
+
+```bash
+# Generate a cost report (FOCUS format)
+redisctl cloud cost-report generate --start 2026-01-01 --end 2026-01-31
+
+# Download a generated report
+redisctl cloud cost-report download --id <report-id>
+
+# Generate and download in one step
+redisctl cloud cost-report export --start 2026-01-01 --end 2026-01-31
+```
+
+## Account Management
+
+```bash
+# Get account details
+redisctl cloud account get
+
+# List/manage users
+redisctl cloud user list
+redisctl cloud user create --data '{...}'
+
+# ACL management
+redisctl cloud acl list
+redisctl cloud acl create --data '{...}'
+```
+
+## Tips
+
+- Use `--profile <name>` to target a specific Cloud profile
+- Use `--output json` for machine-readable output
+- Most create/update commands accept `--data` with a JSON payload or `--file` for a JSON file
+- Task IDs are returned from async operations -- use `cloud task wait` to block until completion

skills/redisctl-database-connect/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: redisctl-database-connect
+description: Connect to Redis databases using the redisctl CLI. Use when opening redis-cli sessions, managing connection profiles, or working with multiple Redis clusters.
+---
+
+## Overview
+
+Connect to Redis databases using profile-based credential management. Supports direct Redis connections, Cloud databases, and Enterprise databases.
+
+## Quick Connect
+
+```bash
+# Open redis-cli using the default database profile
+redisctl db open
+
+# Open redis-cli with a specific profile
+redisctl db open --profile my-redis
+```
+
+## Profile-Based Connection Management
+
+### Create Database Profiles
+
+```bash
+# Local Redis
+redisctl profile set local --type database --url "redis://localhost:6379"
+
+# Redis with password
+redisctl profile set staging --type database --url "redis://:password@host:6379"
+
+# Redis with TLS
+redisctl profile set prod --type database --url "rediss://host:6380"
+
+# Set as default
+redisctl profile default-database local
+```
+
+### Multi-Cluster Workflows
+
+Create profiles for each environment:
+
+```bash
+redisctl profile set dev-redis --type database --url "redis://dev:6379"
+redisctl profile set staging-redis --type database --url "rediss://staging:6380"
+redisctl profile set prod-redis --type database --url "rediss://prod:6380"
+```
+
+Switch between them:
+
+```bash
+# Connect to dev
+redisctl db open --profile dev-redis
+
+# Connect to staging
+redisctl db open --profile staging-redis
+```
+
+## Raw API Access
+
+For operations not covered by specific commands:
+
+```bash
+# Cloud API
+redisctl api cloud GET /subscriptions
+redisctl api cloud POST /subscriptions/12345/databases --data '{...}'
+
+# Enterprise API
+redisctl api enterprise GET /v1/bdbs
+redisctl api enterprise PUT /v1/bdbs/1 --data '{...}'
+```
+
+## Tips
+
+- Database profile URLs follow the standard Redis URI scheme: `redis://[user:password@]host[:port][/db]`
+- Use `rediss://` (double s) for TLS connections
+- Profile credentials support environment variable substitution: `--url "redis://:${REDIS_PASSWORD}@host:6379"`
+- Run `redisctl profile validate` to test all profile connections