Add AI skills for ramenctl commands

.cursor/rules/project.mdc

@@ -64,3 +64,4 @@ Content guidelines:
 
 Footer:
 - Include `Assisted-by: Cursor/{model}` footer with full model version (e.g., `Cursor/Claude Opus 4.6`)
+- NEVER add `Co-authored-by` trailer - we use only `Assisted-by`

README.md

@@ -84,6 +84,18 @@ Your system is ready for disaster recovery!
 
 Please see [Documentation](#documentation) to learn more.
 
+## Agentic usage
+
+*ramenctl* is agentic-ready out of the box. Running `ramenctl init` installs AI
+skills that teach your coding assistant how to configure, validate, gather
+diagnostics, and test disaster recovery flows.
+
+```console
+$ ramenctl init -a cursor
+```
+
+See [AI Skills](docs/skills.md) for details.
+
 ## Documentation
 
 Visit the docs below to learn about *ramenctl* commands:
@@ -95,6 +107,7 @@ Visit the docs below to learn about *ramenctl* commands:
 
 Check the guides below to learn more:
 
+- [Using ramenctl with AI agents](docs/skills.md)
 - [Testing disaster recovery with ramenctl](docs/testing.md)
 
 ## Contributing

cmd/commands/init.go

@@ -4,33 +4,56 @@
 package commands
 
 import (
+	"fmt"
 	"os"
+	"strings"
 
 	"github.com/spf13/cobra"
 
 	"github.com/ramendr/ramenctl/pkg/config"
 	"github.com/ramendr/ramenctl/pkg/console"
+	"github.com/ramendr/ramenctl/pkg/skills"
 )
 
-var envFile string
+var (
+	envFile   string
+	agentName string
+)
 
 var InitCmd = &cobra.Command{
 	Use:   "init",
-	Short: "Create configuration file for your clusters",
+	Short: "Create configuration file and install AI skills",
+	// Validate flags early so cobra shows usage on invalid input.
+	PreRunE: func(c *cobra.Command, args []string) error {
+		return skills.ValidateAgent(agentName)
+	},
 	Run: func(c *cobra.Command, args []string) {
-		if err := config.CreateSampleConfig(
-			configFile,
-			RootCmd.DisplayName(),
-			envFile,
-		); err != nil {
-			_ = console.Failed(err)
+		if err := runInit(); err != nil {
 			os.Exit(1)
 		}
-		console.Completed("Created config file %q - please modify for your clusters", configFile)
 	},
 }
 
 func init() {
-	// Register the --envfile flag
 	InitCmd.Flags().StringVar(&envFile, "envfile", "", "ramen testing environment file")
+	InitCmd.Flags().StringVarP(&agentName, "agent", "a", skills.AgentGeneric,
+		fmt.Sprintf("AI agent to install skills for (%s)", strings.Join(skills.Agents(), ", ")))
+}
+
+func runInit() error {
+	commandName := RootCmd.DisplayName()
+
+	console.Info("Using config %q", configFile)
+	console.Step("Initializing")
+
+	if !config.Install(configFile, commandName, envFile) {
+		return console.Failed(fmt.Errorf("init failed"))
+	}
+
+	if !skills.Install(commandName, agentName) {
+		return console.Failed(fmt.Errorf("init failed"))
+	}
+
+	console.Completed("Init completed")
+	return nil
 }

docs/gather.md

@@ -33,6 +33,10 @@ Use "ramenctl gather [command] --help" for more information about a command.
 > [Configuring common options](docs/init.md#configuring-common-options) to learn
 > how to create one.
 
+> [!TIP]
+> Your AI agent can look up applications and run gather commands for you using
+> the skills installed by `ramenctl init`.
+
 ## gather application
 
 The gather application command gathers data for a specific disaster recover

docs/init.md

@@ -6,32 +6,41 @@ SPDX-License-Identifier: Apache-2.0
 # ramenctl init
 
 The init command crates a configuration file required for other *ramenctl*
-commands.
+commands and installs AI agent skills for other *ramenctl* commands.
 
 ```console
 % ramenctl init -h
-Create configuration file for your clusters
+Create configuration file and install AI skills
 
 Usage:
   ramenctl init [flags]
 
 Flags:
+  -a, --agent string     AI agent to install skills for (bob, claude, codex, cursor, generic) (default "generic")
       --envfile string   ramen testing environment file
   -h, --help             help for init
 
 Global Flags:
   -c, --config string   configuration file (default "config.yaml")
+      --interactive     enable interactive features (default auto)
 ```
 
-## Creating a configuration file
+## Getting started
 
 The init command creates a configuration file named "config.yaml" in the current
-directory:
+and installs AI skills in the current directory:
 
 ```console
 $ ramenctl init
+⭐ Using config "config.yaml"
 
-✅ Created config file "config.yaml" - please modify for your clusters
+🔎 Initializing ...
+   ✅ Created config file "config.yaml" - please modify for your clusters
+   ✅ Created skills in ".agents/skills/"
+   ✅ Created context file "AGENTS.md"
+      Instruct your agent to read AGENTS.md
+
+✅ Init completed
 ```
 
 > [!IMPORTANT]
@@ -40,16 +49,39 @@ $ ramenctl init
 
 Other *ramenctl* commands use "config.yaml" by default.
 
+### AI skills
+
+`ramenctl init` installs AI agent skills alongside the configuration file in the
+current directory. After running `init`, the directory is ready for agentic
+usage out of the box.
+
+Use the `--agent` (`-a`) flag to install skills in the format expected by your
+AI tool (e.g. `ramenctl init -a cursor`). The default generic format works with
+any agent.
+
+Running `init` again is safe. Existing skill files and context files are not
+overwritten, preserving any user modifications.
+
+For more details on available skills, supported agents, and output directory
+conventions, see [AI Skills](skills.md).
+
 ## Creating configuration file for a ramen testing environment
 
 When using a ramen testing environment we can create a configuration file
 optimized for the testing environment using the `--envfile` option:
 
 ```console
 $ ramenctl init --envfile ../ramen/test/envs/regional-dr.yaml
+⭐ Using config "config.yaml"
 ⭐ Using envfile "../ramen/test/envs/regional-dr.yaml"
 
-✅ Created config file "config.yaml" - please modify for your clusters
+🔎 Initializing ...
+   ✅ Created config file "config.yaml" - please modify for your clusters
+   ✅ Created skills in ".agents/skills/"
+   ✅ Created context file "AGENTS.md"
+      Instruct your agent to read AGENTS.md
+
+✅ Init completed
 ```
 
 You can edit the configuration file to change the default tests.
@@ -64,8 +96,15 @@ Create a configuration file named "myenv.yaml":
 
 ```console
 $ ramenctl init --config myenv.yaml
+⭐ Using config "myenv.yaml"
+
+🔎 Initializing ...
+   ✅ Created config file "myenv.yaml" - please modify for your clusters
+   ✅ Created skills in ".agents/skills/"
+   ✅ Created context file "AGENTS.md"
+      Instruct your agent to read AGENTS.md
 
-✅ Created config file "myenv.yaml" - please modify for your clusters
+✅ Init completed
 ```
 
 To use the configuration file with other commands, specify it with the
@@ -83,6 +122,10 @@ $ ramenctl test run --config myenv.yaml -o test
 All *ramenctl* commands require the `clusters` and `clusterSet` options. For the
 validate and gather commands, these are the only options needed.
 
+> [!TIP]
+> You can ask your AI agent to configure the options for your environment using
+> the skills installed by `ramenctl init`.
+
 > [!TIP]
 > When using a ramen testing environment, the `--envfile` option configures
 > everything for you. See

docs/skills.md

@@ -0,0 +1,116 @@
+<!-- SPDX-FileCopyrightText: The RamenDR authors -->
+
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Using ramenctl with AI agents
+
+*ramenctl* is agentic-ready out of the box. Running `ramenctl init` installs AI
+skills that teach your coding assistant how to drive *ramenctl* for disaster
+recovery on your clusters — no extra setup needed.
+
+Start with the example session below to see what this feels like in practice.
+After that you'll find the list of available skills, where they are installed,
+and how to add support for a new agent.
+
+## Example session
+
+The following is a short screenplay-style scene: a human and an agent use the
+ramenctl skills. (Monospace block so it reads like a script and renders with a
+distinct background on GitHub and most viewers.)
+
+```text
+INT. CURSOR CHAT — DAY
+
+USER
+        I ran ramenctl init --agent cursor. Help me configure ramenctl
+        for my clusters. My kubeconfigs are in ocp/: hub.yaml is the
+        hub, c1.yaml and c2.yaml are the managed clusters.
+
+AGENT
+        (Edits config.yaml: fills kubeconfigs, reads ClusterClaims on c1
+        and c2, matches names on the hub, sets clusterSet.)
+        Your config is ready.
+
+USER
+        Can you check the clusters?
+
+AGENT
+        (Runs ramenctl validate clusters -o ocp/clusters.)
+        Validation completed (91 ok, 0 warning, 0 problem).
+        (Opens validate-clusters.html in the browser.)
+
+USER
+        Validate an application too.
+
+AGENT
+        (Lists DRPCs on the hub.)
+        I found two applications:
+          1. rbd4 (openshift-dr-ops) — FailedOver
+          2. appset-deploy-rbd (openshift-gitops) — Deployed
+        Which one should I validate?
+
+USER
+        rbd4.
+
+AGENT
+        (Runs ramenctl validate application --name rbd4 --namespace
+        openshift-dr-ops -o ocp/rbd4.)
+        All clear. Opening validate-application.html.
+
+USER
+        You are a very skillful agent!
+
+AGENT
+        Glad it helped.
+```
+
+## Available skills
+
+| Skill                           | Description                                        |
+| ------------------------------- | -------------------------------------------------- |
+| `ramenctl-init`                 | Create a configuration file for your clusters      |
+| `ramenctl-validate-clusters`    | Validate disaster recovery cluster configuration   |
+| `ramenctl-validate-application` | Validate a DR-protected application                |
+| `ramenctl-gather-application`   | Gather diagnostic data for a protected application |
+| `ramenctl-test-run`             | Run disaster recovery flow tests                   |
+| `ramenctl-test-clean`           | Clean up after test runs                           |
+
+## Where skills are installed
+
+`ramenctl init` installs skills automatically. Use the `--agent` (`-a`) flag to
+install in the format expected by your AI tool:
+
+```console
+$ ramenctl init -a cursor
+```
+
+Supported agents:
+
+| Agent       | Flag        | Skills directory  | Context file                 |
+| ----------- | ----------- | ----------------- | ---------------------------- |
+| Bob         | `-a bob`    | `.bob/skills/`    | `AGENTS.md`                  |
+| Claude Code | `-a claude` | `.claude/skills/` | `CLAUDE.md`                  |
+| Codex       | `-a codex`  | `.agents/skills/` | `AGENTS.md`                  |
+| Cursor      | `-a cursor` | `.cursor/skills/` | `.cursor/rules/ramenctl.mdc` |
+| Generic     | *(default)* | `.agents/skills/` | `AGENTS.md`                  |
+
+> [!TIP]
+> - When using the generic format, instruct your AI agent to read `AGENTS.md`
+>   for project context and skill discovery.
+> - Bob requires advanced mode to discover skills. Use `/mode advanced` in the
+>   Bob chat before starting.
+
+See [init](init.md) for more on creating the configuration file.
+
+## Adding a new agent
+
+To add support for a new AI agent:
+
+1. Add a constant (e.g. `AgentMyTool = "my-agent"`) in `pkg/skills/agent.go`.
+1. Add an entry to the `agents` map in `pkg/skills/agent.go` with the tool's
+   display name, native skills directory, and context file path.
+1. Create a context file template `pkg/skills/templates/agents/my-agent.tmpl`.
+   The template receives the command name and skill list. Look at existing
+   templates for examples.
+1. Update the agent table in `docs/skills.md`.
+1. Add test cases in `pkg/skills/skills_test.go` for the new agent.

docs/test.md

@@ -39,6 +39,10 @@ The command supports the following sub-commands:
 > The test command requires a configuration file. See [init](docs/init.md) to
 > learn how to create one.
 
+> [!TIP]
+> Your AI agent can configure tests and run them for you using the skills
+> installed by `ramenctl init`.
+
 ## test run
 
 The run command runs a disaster recovery flow with one or more tiny applications