refactor rules into skills. improve skills

Author: tuvia-akeyless

.cursor/rules/general.mdc

@@ -53,6 +53,7 @@ The old `resource_gateway_producer_*` resources are the legacy format of dynamic
 - **`Sensitive: true`** — secrets, passwords, private keys, API keys, tokens, client secrets
 - **`Default` type must match `Type`** — e.g. `Default: 0` for `TypeInt`, `Default: false` for `TypeBool` (never use string `"0"` or `"false"`)
 - **`ForceNew: true`** — for the item's identifier field (e.g. `name`)
+- **`DiffSuppressFunc: common.DiffSuppressOnLeadingSlash`** — for any field that holds an **Akeyless item path** (e.g. `name`, issuer name, cert issuer, signer, target path, folder path). The API returns these paths with a leading `/`; without the suppressor the plan is never empty.
 - **`id`** is a reserved field in Terraform — do not use it as a custom schema field name; use a prefixed name like `migration_id` instead
 - All `d.Set()` calls in read functions **must** check for errors
 - When updating tags, use `common.GetTagsForUpdate` to handle both add and remove

.cursor/rules/item-description-field.mdc

@@ -1,13 +1,10 @@
 ---
-description: Rules for adding a new command (resource/data source) to the Terraform provider
-globs: akeyless/*.go
-alwaysApply: false
+name: add-new-command
+description: Guides adding a new Terraform resource or data source end-to-end — SDK update, schema, CRUD, provider registration, tests, and formatting. Use when creating a new resource_*.go or data_source_*.go file, or when the user asks to add a new Terraform resource.
 ---
 
 # Adding a New Command (Resource or Data Source)
 
-When adding a new resource or data source to the Terraform provider, follow these steps:
-
 ## 1. Update the Akeyless SDK
 
 1.  Run `go get -u github.com/akeylesslabs/akeyless-go/v5`
@@ -57,41 +54,41 @@ func resourceMyNewFeatureCreate(ctx context.Context, d *schema.ResourceData, m i
 
 ### Schema Field Rules
 
-When defining schema fields, follow these conventions:
 - **`Sensitive: true`** — for secrets, passwords, private keys, API keys, tokens, and client secrets
 - **`Computed: true`** — when the field has server-side defaults (e.g. protection keys)
 - **`Default`** — must match the field's `Type` (e.g. `Default: 0` for `TypeInt`, `Default: false` for `TypeBool`; never use string `"0"` or `"false"`)
 - **`Required` / `Optional`** — according to the SDK command requirements. If `Optional` is true, `Required` can be omitted.
 - **`ForceNew: true`** — for the field (or few fields, in special cases) that identify the item (e.g. `name`)
+- **`DiffSuppressFunc: common.DiffSuppressOnLeadingSlash`** — for any field that holds an Akeyless item path (e.g. `name`, issuer, signer, target path, folder). The API returns paths with a leading `/`; without the suppressor the plan is never empty.
 - **`id`** — reserved by Terraform; do not use as a custom schema field
 - All `d.Set()` calls in read functions **must** check for errors
 - Read functions must set **every writable field** that the API response exposes (skip Sensitive fields the API won't return)
 - When a resource replaces a legacy one, add `DeprecationMessage` to the old resource pointing to the new one
 - The Update handler must use an "override" approach -- always set all fields, not just the ones that are explicitly configured. Set all fields that the SDK support to update.
 
-## 3. Register the New Command
+## 4. Register the New Command
 
 1.  Open `akeyless/provider.go`.
 2.  Add the new resource to `ResourcesMap` or data source to `DataSourcesMap` in the `Provider()` function.
     *   Key: `akeyless_<name>` (e.g., `akeyless_my_new_feature`)
     *   Value: Function call (e.g., `resourceMyNewFeature()`)
 
-## 4. Documentation
+## 5. Documentation
 
 Documentation is auto-generated.
 
 1.  Ensure all schema fields have clear `Description`s.
 2.  Run `go generate` in the root directory.
 3.  This will create the documentation file in `docs/resources/` or `docs/data-sources/`.
 
-## 5. Testing
+## 6. Testing
 
 1.  Add tests to an existing or new test file (not required to create a separate file per resource).
 2.  Implement acceptance tests using `resource.TestCase`.
 3.  Try to cover as much as input arguments, especially the arguments that are unique to the resource.
 4.  For arguments with default value, ensure the updateConfig (step 2) set them to empty. This will add coverage for the defaulting mechanism.
 5.  Run tests: `make testacc TEST=./akeyless/resource_<name>_test.go` (or similar).
 
-## 6. Format
+## 7. Format
 
 Run `gofmt -w .` to ensure code style compliance.

.cursor/rules/add-new-command.mdc .cursor/skills/add-new-command/SKILL.md.cursor/rules/add-new-command.mdc renamed to .cursor/skills/add-new-command/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: item-description-field
+description: Correct field to use for item descriptions in Read functions — ItemMetadata for DescribeItem, Description for specific Get endpoints. Use when implementing or reviewing d.Set("description", ...) in resource read functions.
+---
+
+# Item Description Field Pattern
+
+When reading item descriptions in resource Read functions, use the correct field based on the API call.
+
+## DescribeItem API
+
+Use `ItemMetadata`:
+
+```go
+if rOut.ItemMetadata != nil {
+    err = d.Set("description", *rOut.ItemMetadata)
+    if err != nil {
+        return err
+    }
+}
+```
+
+**Do not use** `ItemGeneralInfo.DisplayMetadata`.
+
+## Specific Get Endpoints
+
+Use the direct `Description` field from the response structure.

.cursor/skills/item-description-field/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: test-fixture-setup
+description: Create test fixture dependencies (keys, issuers, targets, secrets) via SDK API calls in test setup, not via Terraform depends_on. Use when writing or reviewing acceptance tests that need pre-existing items, or when a test fails because a Terraform resource references an item that doesn't exist.
+---
+
+# Test Fixture Setup
+
+## Rule
+
+When an acceptance test resource depends on a pre-existing item (e.g. a gateway config resource that references an SSH cert issuer), create that item **via the SDK API** in the test function body, not as a Terraform resource with `depends_on`.
+
+**Why:** Terraform resources inside test configs can fail with ordering issues, and mixing infrastructure setup with the resource under test makes failures harder to diagnose. API-created fixtures are deterministic and independent of the Terraform run.
+
+## Pattern
+
+```go
+func TestMyResource(t *testing.T) {
+    testutils.SkipIfNoGateway(t)
+
+    // 1. Create fixtures via API
+    keyPath := testPath("my_key")
+    testutils.CreateDfcKey(t, keyPath)
+    t.Cleanup(func() {
+		testutils.DeleteItem(t, keyPath)
+	})
+
+    issuerPath := testPath("my_issuer")
+    testutils.CreateSshCertIssuer(t, keyPath, issuerPath, "test")
+    t.Cleanup(func() {
+		testutils.DeleteItem(t, issuerPath)
+	})
+
+    // 2. Reference fixtures by path in Terraform config
+    config := fmt.Sprintf(`
+        resource "akeyless_my_resource" "%v" {
+            some_item_ref = "%v"
+            other_field   = "value1"
+        }
+    `, name, issuerPath)
+
+    configUpdate := fmt.Sprintf(`
+        resource "akeyless_my_resource" "%v" {
+            some_item_ref = "%v"
+            other_field   = "value2"
+        }
+    `, name, issuerPath)
+
+    testutils.TestGatewayConfigResource(t, providerFactories, config, configUpdate)
+}
+```
+
+## Available Helpers
+
+All in `akeyless/tests/testutils/testutils.go`:
+
+| Helper | Creates | Requires |
+|--------|---------|----------|
+| `CreateDfcKey(t, name)` | DFC key (RSA1024) | — |
+| `CreateProtectionKey(t, name)` | AES128-GCM key | — |
+| `CreateSshCertIssuer(t, keyName, issuerName, users)` | SSH cert issuer | DFC key |
+| `CreatePkiCertIssuer(t, keyName, issuerName, destPath, cn, uriSan)` | PKI cert issuer | DFC key |
+| `CreateCertificate(t, certName, certB64, keyB64)` | Certificate item | Generated cert/key pair |
+| `CreateSecret(t, *TestSecret)` | Static secret | — |
+| `DeleteItem(t, path)` | — | Always `defer` after create |
+| `DeleteItemIfExists(t, path)` | — | Silent if missing |
+
+## Cleanup
+
+Always `defer testutils.DeleteItem(t, path)` immediately after each create call, before the next create. This ensures cleanup runs in reverse order even if a later create fails.

.cursor/skills/test-fixture-setup/SKILL.md

@@ -1,19 +1,15 @@
 ---
-description: Rules for updating an existing command/resource in the Terraform provider
-globs: akeyless/*.go
-alwaysApply: false
+name: update-existing-command
+description: Guides updating an existing Terraform resource or data source with new fields or functionality — schema changes, CRUD updates, backward compatibility, and docs regeneration. Use when adding fields to an existing resource_*.go or data_source_*.go file.
 ---
 
 # Updating an Existing Command/Resource
 
-When updating an existing command (resource or data source) to support new fields or functionality, follow these steps:
-
 ## 1. Update the Akeyless SDK
 
 1.  Run `go get -u github.com/akeylesslabs/akeyless-go/v5`
 2.  Run `go mod tidy`
 
-
 ## 2. Update the Resource/Data Source Implementation
 
 1.  Identify the relevant file in the `akeyless/` directory (e.g., `resource_<name>.go`).