From c174ad7d637f785dc844a3cf08b4baf2a0e73b13 Mon Sep 17 00:00:00 2001 From: Mun-GitHub Date: Mon, 12 Oct 2026 16:15:25 +0530 Subject: [PATCH 1/8] feat(skills): add asset-management skill for the Assets DAM product Advisory skill covering spaces and workspaces, folders, asset types and metadata, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, image editing, and CMS integration. Registered in the router, README and manifest; cursor rules and codex tree regenerated. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 3 +- codex/AGENTS.md | 1 + codex/asset-management/SKILL.md | 194 +++++++++++++++++ cursor/rules/00-router.mdc | 1 + cursor/rules/01-asset-management.mdc | 197 ++++++++++++++++++ ...sistant.mdc => 02-brand-kit-assistant.mdc} | 0 .../{02-cms-assets.mdc => 03-cms-assets.mdc} | 0 ...liases.mdc => 04-cms-branches-aliases.mdc} | 0 ...> 05-cms-data-modeling-best-practices.mdc} | 0 ...{05-cms-entries.mdc => 06-cms-entries.mdc} | 0 ...mdc => 07-cms-environments-publishing.mdc} | 0 ...view-visual-builder-support-assistant.mdc} | 0 ...calization.mdc => 09-cms-localization.mdc} | 0 ...9-cms-releases.mdc => 10-cms-releases.mdc} | 0 ...sions.mdc => 11-cms-roles-permissions.mdc} | 0 ...1-cms-taxonomy.mdc => 12-cms-taxonomy.mdc} | 0 ...n.mdc => 13-cms-tokens-authentication.mdc} | 0 ...dc => 14-cms-variants-personalization.mdc} | 0 ...4-cms-webhooks.mdc => 15-cms-webhooks.mdc} | 0 ...cms-workflows.mdc => 16-cms-workflows.mdc} | 0 ...mdc => 17-developer-hub-app-architect.mdc} | 0 ...elivery-sdk.mdc => 18-dx-delivery-sdk.mdc} | 0 ...sdk.mdc => 19-dx-migrate-js-to-ts-sdk.mdc} | 0 ...nvironment-variables-from-env-example.mdc} | 0 ...rigger-and-monitor-launch-deployments.mdc} | 0 ...mpanion.mdc => 22-migration-companion.mdc} | 0 manifest.json | 7 +- skills/CLAUDE.md | 1 + skills/asset-management/SKILL.md | 197 ++++++++++++++++++ 29 files changed, 599 insertions(+), 2 deletions(-) create mode 100644 codex/asset-management/SKILL.md create mode 100644 cursor/rules/01-asset-management.mdc rename cursor/rules/{01-brand-kit-assistant.mdc => 02-brand-kit-assistant.mdc} (100%) rename cursor/rules/{02-cms-assets.mdc => 03-cms-assets.mdc} (100%) rename cursor/rules/{03-cms-branches-aliases.mdc => 04-cms-branches-aliases.mdc} (100%) rename cursor/rules/{04-cms-data-modeling-best-practices.mdc => 05-cms-data-modeling-best-practices.mdc} (100%) rename cursor/rules/{05-cms-entries.mdc => 06-cms-entries.mdc} (100%) rename cursor/rules/{06-cms-environments-publishing.mdc => 07-cms-environments-publishing.mdc} (100%) rename cursor/rules/{07-cms-live-preview-visual-builder-support-assistant.mdc => 08-cms-live-preview-visual-builder-support-assistant.mdc} (100%) rename cursor/rules/{08-cms-localization.mdc => 09-cms-localization.mdc} (100%) rename cursor/rules/{09-cms-releases.mdc => 10-cms-releases.mdc} (100%) rename cursor/rules/{10-cms-roles-permissions.mdc => 11-cms-roles-permissions.mdc} (100%) rename cursor/rules/{11-cms-taxonomy.mdc => 12-cms-taxonomy.mdc} (100%) rename cursor/rules/{12-cms-tokens-authentication.mdc => 13-cms-tokens-authentication.mdc} (100%) rename cursor/rules/{13-cms-variants-personalization.mdc => 14-cms-variants-personalization.mdc} (100%) rename cursor/rules/{14-cms-webhooks.mdc => 15-cms-webhooks.mdc} (100%) rename cursor/rules/{15-cms-workflows.mdc => 16-cms-workflows.mdc} (100%) rename cursor/rules/{16-developer-hub-app-architect.mdc => 17-developer-hub-app-architect.mdc} (100%) rename cursor/rules/{17-dx-delivery-sdk.mdc => 18-dx-delivery-sdk.mdc} (100%) rename cursor/rules/{18-dx-migrate-js-to-ts-sdk.mdc => 19-dx-migrate-js-to-ts-sdk.mdc} (100%) rename cursor/rules/{19-launch-sync-environment-variables-from-env-example.mdc => 20-launch-sync-environment-variables-from-env-example.mdc} (100%) rename cursor/rules/{20-launch-trigger-and-monitor-launch-deployments.mdc => 21-launch-trigger-and-monitor-launch-deployments.mdc} (100%) rename cursor/rules/{21-migration-companion.mdc => 22-migration-companion.mdc} (100%) create mode 100644 skills/asset-management/SKILL.md diff --git a/README.md b/README.md index a6cbbbd..8a190c2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Contentstack Skills -A bundle of 21 ready-to-use [Contentstack](https://www.contentstack.com) agent skills for AI coding tools, covering CMS implementation, Brand Kit guidance, delivery SDK development, migration workflows, Developer Hub app architecture, and Launch automation. +A bundle of 22 ready-to-use [Contentstack](https://www.contentstack.com) agent skills for AI coding tools, covering CMS implementation, Brand Kit guidance, delivery SDK development, migration workflows, Developer Hub app architecture, and Launch automation. ## What's in here? @@ -51,6 +51,7 @@ npx skills add @ | Slug | Title | Product | What it helps with | | --- | --- | --- | --- | +| `asset-management` | Asset Management | Assets | Assets DAM spaces and workspaces, folders, asset types and metadata, AI tagging and alt text, duplicate management, versions, trash and restore, visual markups, and CMS integration. | | `brand-kit-assistant` | Brand Kit Assistant | Brand Kit | Brand Kit concepts, setup, governance, Voice Profiles, Knowledge Vault, on-brand AI generation, and API-task routing. | | `cms-assets` | Contentstack Assets | CMS | Asset organization, image transformations, publishing lifecycle, CDN behavior, and asset limits. | | `cms-branches-aliases` | Branches & Aliases | CMS | Isolated content development, alias-based deployments, CI/CD integration, merge behavior, and rollback patterns. | diff --git a/codex/AGENTS.md b/codex/AGENTS.md index e86f870..14c88d6 100644 --- a/codex/AGENTS.md +++ b/codex/AGENTS.md @@ -11,6 +11,7 @@ Use the table below to route a user request to the right skill. Each row maps a | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) | | Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](./cms-live-preview-visual-builder-support-assistant/SKILL.md) | | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) | +| Use when a user asks about the Contentstack Assets DAM product: spaces and workspaces, folders, asset types and metadata, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, image editing, or linking Assets to CMS stacks. Not for the CMS stack asset library (use cms-assets). | [Asset Management](./asset-management/SKILL.md) | | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](./cms-assets/SKILL.md) | | Use when developers need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. | [Contentstack Taxonomy](./cms-taxonomy/SKILL.md) | | Use when developers ask about workflow stage design, approval processes, publish rules, self-approval prevention, transition restrictions, or automation triggered by workflow changes. | [Workflows & Publish Rules](./cms-workflows/SKILL.md) | diff --git a/codex/asset-management/SKILL.md b/codex/asset-management/SKILL.md new file mode 100644 index 0000000..6f3ae2a --- /dev/null +++ b/codex/asset-management/SKILL.md @@ -0,0 +1,194 @@ +# asset-management + + +# Asset Management (Contentstack Assets DAM) + +## Description + +Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, image editing, and CMS integration. + +## When to Use + +Use when a user asks about the Contentstack Assets DAM: organizing assets in spaces, workspaces and folders, modeling asset metadata, AI tags and alt text, finding and removing duplicates, versioning, restoring deleted assets, visual markups, or using Assets with a CMS stack. + +Do not use for the CMS stack asset library (stack-level uploads, folders, Image Delivery API, publishing to environments). Route those questions to `cms-assets`. If it is unclear which one the user means, ask whether they work in an Assets space or in the asset library inside a stack. + +## User Problem + +Teams adopting Contentstack Assets need to structure spaces and workspaces sensibly, model metadata so assets are findable, use AI features safely, keep the library free of duplicates, and understand what is and is not recoverable when assets are deleted or replaced. + +## Success Criteria + +- Distinguish the Assets DAM from the CMS asset library. +- Use the product's own terminology: space, workspace, main workspace, asset type, system metadata, user-defined metadata, duplicate set, visual markup. +- State documented behavior and limits accurately, and say plainly when something is not documented. +- Warn about irreversible or hard-to-reverse actions before the user takes them. + +## Expected Inputs + +- Which product the user means (Assets space or CMS stack library) +- Organization shape (brands, regions, teams) and number of spaces +- Asset types and metadata the team needs +- The specific task or problem (duplicates, restore, versions, AI settings, markups) + +## Expected Outputs + +- Space, workspace and folder structure recommendations +- Asset type and metadata modeling guidance +- Step-by-step UI paths for the task +- Gotchas and irreversible-action warnings +- Pointers to the official docs for anything not covered here + +## Example User Requests + +- How should I split my brands and regions across spaces and workspaces? +- How do I add custom fields to my images? +- Can Assets tag my images and write alt text automatically? +- How do I find and remove duplicate images? +- I deleted a folder by mistake. Can I get it back? +- How do I roll back to an earlier version of an asset? +- How do I add hotspots to a product image? +- How do I use assets from a space in my CMS entries? + +## Workflow Summary + +1. Confirm the user means the Assets DAM, not the CMS asset library. +2. Identify the topic: structure, metadata, AI, duplicates, versions, trash, markups, editing, or CMS integration. +3. Answer with documented behavior using the product's terminology. +4. Flag limits and irreversible actions. +5. Link to the relevant docs page for anything undocumented or likely to change. + +## Instructions + +### Spaces and workspaces + +- A **space** is the top-level container, often one per brand, business unit or region. Roles, permissions and settings are governed at the space level, so each space is managed independently. +- A **workspace** is an isolated environment inside a space. Every space has a **main workspace**. New workspaces are created from the main workspace or from another parent workspace, inherit its assets, metadata and configuration, and keep their own changes isolated from the parent. +- A space can be linked to one or more CMS stacks, and assets can be reused across stacks. +- Recommend a small number of spaces and workspaces. Over-fragmenting adds management overhead. +- Space Settings > General holds the title (required) and description. The Space UID is generated by the system and cannot be changed. +- Deleting a space is irreversible. It removes the space's assets, users and collaborators. Always warn before recommending it. +- Duplicate Management is configured per workspace. AI Settings live under Space Settings. + +### Folders + +- Create a folder with **+ New > New Folder**. Name is required and description is optional. Folders appear in the listing and in the Folders section of the Filters panel. +- Recommend a folder structure that matches how teams search, such as by campaign, asset category or brand, and keep it consistent across workspaces. + +### Roles and permissions + +- Access is governed per space through roles, teams and associations. Where the user needs the exact predefined roles or asset-level sharing options, direct them to the current Assets documentation rather than guessing. +- For least privilege, give contributors only the access they need and restrict delete and settings permissions to a few administrators. + +### Asset types and metadata + +- Metadata comes in layers: **system metadata** (read-only: file name, UID, URLs, MIME type, size, created and modified details), **general metadata**, and **user-defined metadata** from custom fields. +- Each **asset type** maps to one MIME type and one file extension. On upload, a matching type applies automatically and its fields appear. System types cover images, audio, video, documents and archives, and you can add custom types. +- User-defined fields are reusable across asset types. Documented field types include single line textbox, multi line textbox, link, select (dropdown, radio buttons or checkboxes), number, date, boolean and group. +- The set of supported field types has been expanding. Tell the user to confirm the current list in the Asset Modeling docs before designing around a specific type. +- Mandatory fields must be filled before an upload or save can finish. Use them sparingly so uploads are not blocked on optional information. +- Edit metadata for an individual asset in the configurable metadata panel. + +### AI tags, alt text and colors + +- In the metadata panel, **Suggest Tags with AI** and **Suggest Description with AI** generate suggestions. AI can also extract dominant colors, which powers color-based filtering. Suggestions can be wrong, so review them before saving. +- **Auto-populate at upload** is configured in Space Settings > AI Settings. Enable the AI Tags and Alt Text toggles, set Advanced Properties, and click Save Properties. + - Applies to images and to new uploads only. Existing assets are not enriched, and replacing a file does not trigger it. + - Values are written into version 1. No extra version is created, nothing waits for review, and uploads are not slowed down. + - It never overwrites a value the uploader entered. It only fills empty destinations. + - Tags: up to 10 per asset. Confidence ranges from 10% to 100%, and the default is 10 tags at 80%. Tagging adds tags and never removes existing ones. + - Alt text is English only. It goes to the system Description field or to one single-line textbox field you choose. It is skipped if the destination already has a value, or if the chosen field is missing from the asset's type or was deleted or changed type. Tags are still written in those cases. + +### Duplicate management + +- Detects **exact duplicates** (byte-identical images). Two or more form a **duplicate set**, and no copy is treated as the original. +- Images only, and a set cannot span workspaces. Detection is on by default in every workspace and runs in the background after upload, replace, delete and restore. It does not block or flag uploads. +- An admin with permission to edit space settings can turn it off per workspace. +- Open it from the asset listing: More Actions > Duplicate Management. Resolve a set by **Keep This, Delete the Rest**, by deleting a single copy, or by bulk-deleting the duplicates. +- Gotchas to state up front: + - Resized, cropped, re-exported or recompressed copies are not detected. + - Duplicate sets cannot be searched, filtered or sorted. + - Users with partial view permission see a partial count. + - Selecting every copy deletes the image, with no warning. + - Deleting a copy removes it everywhere it is used or linked, so check references first. + - A set disappears once fewer than two images remain, and new duplicates can take a moment to appear. + +### Versions + +- Any change to the file or to metadata creates a new version, and so does a Save Assets action. Default names are Version 1, Version 2 and so on. +- Rename a version from the version selector at the top right. The name can be up to 32 characters using letters, numbers, spaces, hyphens and underscores. Renaming does not create a version. +- To restore an earlier version, select it in the version selector and click **Save Asset**. It becomes the latest version, and the older versions stay in history. +- Only users with edit permission can rename or restore. Others can view history. +- Do not mix this with the CMS asset library's History > View flow. They are different products. + +### Trash and restore + +- Deleted assets and folders go to **Trash** (Space Settings > Trash) and can be restored within **14 days** of deletion. After that they are permanently removed. +- Restore with the ⋮ menu > Restore. Managing assets in the workspace is required. Trash can be filtered by who deleted, type and date range. +- For folders, choose **Restore With Assets** or **Restore without Assets**. With Assets restores only the assets that were in the folder when it was deleted. Assets deleted earlier stay in trash. +- If Restore is greyed out, the parent folder is still in trash. Restore the folder first. +- Deleting an asset removes it from entries that use it. Advise checking references before deleting. + +### Visual markups + +- A **visual markup** annotates a region of an image. A **hotspot** is a single point (x and y). A **bounding box** is a rectangle (x, y, width, height). +- Each markup needs a title. Description, URL and position are optional. Typical uses are shoppable images, annotated diagrams and linking related content. +- **Suggest Markup with AI** proposes bounding boxes with confidence scores. Review them before saving. +- Per markup you can edit, duplicate, hide or delete. Bulk actions can hide all markups or **delete all markups, which is permanent**. +- Markups are for interactive and shoppable content. Do not describe them as review comments or annotation threads. + +### Image editing + +- The public documentation for editing images inside Assets is limited. Describe only what the user's current docs confirm, and point them to the Assets docs for the editing options available to them. +- Do not confuse this with delivery-time transformations (crop, fit, orient and so on) in the Image Delivery API, or with the Image Cropper extension. Those belong to the CMS side. + +### CMS integration and delivery + +- Link a space to one or more stacks so its assets can be used in entries. For setup steps, direct the user to the current Assets documentation. +- In the Content Delivery API, the `asset_fields[]` query parameter applies to assets from the new Assets product. Documented values are `visual_markups` and `user_defined_fields`, and the parameter can be repeated. Stack-library assets do not return those keys. +- `visual_markups` is an empty array when an asset has none. A hotspot returns x and y, and a bounding box also returns width and height. +- Do not state CDN host names, URL formats or branch behavior for Assets as fact unless the user's docs confirm them. + +## Output Format + +Be concise and practical. Use the product's terms. Give UI paths as `Menu > Item`. Use short bullets for steps, limits and gotchas. When something is undocumented or uncertain, say so and link to the docs instead of guessing. + +## Tooling Notes + +Read-only advisory skill. Do not upload, move, delete, restore or modify assets, spaces or settings. Explain the steps and let the user perform them. + +References: + +- https://www.contentstack.com/docs/assets/about-assets +- https://www.contentstack.com/docs/assets/about-spaces-and-workspaces +- https://www.contentstack.com/docs/assets/about-asset-modeling +- https://www.contentstack.com/docs/assets/enhance-asset-management-with-ai +- https://www.contentstack.com/docs/assets/manage-duplicate-images +- https://www.contentstack.com/docs/assets/asset-versioning +- https://www.contentstack.com/docs/assets/restore-an-asset-or-folder +- https://www.contentstack.com/docs/assets/add-visual-markups +- https://www.contentstack.com/docs/developers/apis/content-delivery-api/assets + +## Security + +### Defaults + +- Never expose tokens or API keys. +- Use environment variables for credentials in any example code. + +### Destructive Actions + +Do not perform destructive actions. For deleting a space, deleting duplicates, emptying or letting trash expire, or deleting all markups, explain the consequences and the safe checks (references, restore window, selection), then leave execution to the user. + +### Secrets + +Never reveal management tokens, API keys or other secrets. Reference environment variables only. + +## Product Context + +- Product: Assets (DAM) +- Description: Contentstack Assets is the digital asset management layer: spaces, workspaces, folders, asset types and metadata, AI enrichment, duplicate management, versioning, visual markups and CMS integration. +- Product safety rules: + - Never expose management tokens or API keys. + - Always use environment variables for credentials. + - Treat deletion of spaces, assets and markups as irreversible unless the docs state a restore window. diff --git a/cursor/rules/00-router.mdc b/cursor/rules/00-router.mdc index bffe8f7..8cc602e 100644 --- a/cursor/rules/00-router.mdc +++ b/cursor/rules/00-router.mdc @@ -16,6 +16,7 @@ Use the table below to route a user request to the right skill. Each row maps a | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](../../skills/cms-data-modeling-best-practices/SKILL.md) | | Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](../../skills/cms-live-preview-visual-builder-support-assistant/SKILL.md) | | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](../../skills/cms-entries/SKILL.md) | +| Use when a user asks about the Contentstack Assets DAM product: spaces and workspaces, folders, asset types and metadata, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, image editing, or linking Assets to CMS stacks. Not for the CMS stack asset library (use cms-assets). | [Asset Management](../../skills/asset-management/SKILL.md) | | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](../../skills/cms-assets/SKILL.md) | | Use when developers need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. | [Contentstack Taxonomy](../../skills/cms-taxonomy/SKILL.md) | | Use when developers ask about workflow stage design, approval processes, publish rules, self-approval prevention, transition restrictions, or automation triggered by workflow changes. | [Workflows & Publish Rules](../../skills/cms-workflows/SKILL.md) | diff --git a/cursor/rules/01-asset-management.mdc b/cursor/rules/01-asset-management.mdc new file mode 100644 index 0000000..ca09876 --- /dev/null +++ b/cursor/rules/01-asset-management.mdc @@ -0,0 +1,197 @@ +--- +description: "Advise on Contentstack Assets, the standalone digital asset management (DAM) product. Cover spaces and workspaces, folders, asset types and metadata, AI tagging and alt text, duplicate management, versions, trash and restore, visual markups, image editing, and linking to CMS stacks. Not for the CMS stack asset library; use cms-assets for that." +alwaysApply: false +--- + + +# Asset Management (Contentstack Assets DAM) + +## Description + +Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, image editing, and CMS integration. + +## When to Use + +Use when a user asks about the Contentstack Assets DAM: organizing assets in spaces, workspaces and folders, modeling asset metadata, AI tags and alt text, finding and removing duplicates, versioning, restoring deleted assets, visual markups, or using Assets with a CMS stack. + +Do not use for the CMS stack asset library (stack-level uploads, folders, Image Delivery API, publishing to environments). Route those questions to `cms-assets`. If it is unclear which one the user means, ask whether they work in an Assets space or in the asset library inside a stack. + +## User Problem + +Teams adopting Contentstack Assets need to structure spaces and workspaces sensibly, model metadata so assets are findable, use AI features safely, keep the library free of duplicates, and understand what is and is not recoverable when assets are deleted or replaced. + +## Success Criteria + +- Distinguish the Assets DAM from the CMS asset library. +- Use the product's own terminology: space, workspace, main workspace, asset type, system metadata, user-defined metadata, duplicate set, visual markup. +- State documented behavior and limits accurately, and say plainly when something is not documented. +- Warn about irreversible or hard-to-reverse actions before the user takes them. + +## Expected Inputs + +- Which product the user means (Assets space or CMS stack library) +- Organization shape (brands, regions, teams) and number of spaces +- Asset types and metadata the team needs +- The specific task or problem (duplicates, restore, versions, AI settings, markups) + +## Expected Outputs + +- Space, workspace and folder structure recommendations +- Asset type and metadata modeling guidance +- Step-by-step UI paths for the task +- Gotchas and irreversible-action warnings +- Pointers to the official docs for anything not covered here + +## Example User Requests + +- How should I split my brands and regions across spaces and workspaces? +- How do I add custom fields to my images? +- Can Assets tag my images and write alt text automatically? +- How do I find and remove duplicate images? +- I deleted a folder by mistake. Can I get it back? +- How do I roll back to an earlier version of an asset? +- How do I add hotspots to a product image? +- How do I use assets from a space in my CMS entries? + +## Workflow Summary + +1. Confirm the user means the Assets DAM, not the CMS asset library. +2. Identify the topic: structure, metadata, AI, duplicates, versions, trash, markups, editing, or CMS integration. +3. Answer with documented behavior using the product's terminology. +4. Flag limits and irreversible actions. +5. Link to the relevant docs page for anything undocumented or likely to change. + +## Instructions + +### Spaces and workspaces + +- A **space** is the top-level container, often one per brand, business unit or region. Roles, permissions and settings are governed at the space level, so each space is managed independently. +- A **workspace** is an isolated environment inside a space. Every space has a **main workspace**. New workspaces are created from the main workspace or from another parent workspace, inherit its assets, metadata and configuration, and keep their own changes isolated from the parent. +- A space can be linked to one or more CMS stacks, and assets can be reused across stacks. +- Recommend a small number of spaces and workspaces. Over-fragmenting adds management overhead. +- Space Settings > General holds the title (required) and description. The Space UID is generated by the system and cannot be changed. +- Deleting a space is irreversible. It removes the space's assets, users and collaborators. Always warn before recommending it. +- Duplicate Management is configured per workspace. AI Settings live under Space Settings. + +### Folders + +- Create a folder with **+ New > New Folder**. Name is required and description is optional. Folders appear in the listing and in the Folders section of the Filters panel. +- Recommend a folder structure that matches how teams search, such as by campaign, asset category or brand, and keep it consistent across workspaces. + +### Roles and permissions + +- Access is governed per space through roles, teams and associations. Where the user needs the exact predefined roles or asset-level sharing options, direct them to the current Assets documentation rather than guessing. +- For least privilege, give contributors only the access they need and restrict delete and settings permissions to a few administrators. + +### Asset types and metadata + +- Metadata comes in layers: **system metadata** (read-only: file name, UID, URLs, MIME type, size, created and modified details), **general metadata**, and **user-defined metadata** from custom fields. +- Each **asset type** maps to one MIME type and one file extension. On upload, a matching type applies automatically and its fields appear. System types cover images, audio, video, documents and archives, and you can add custom types. +- User-defined fields are reusable across asset types. Documented field types include single line textbox, multi line textbox, link, select (dropdown, radio buttons or checkboxes), number, date, boolean and group. +- The set of supported field types has been expanding. Tell the user to confirm the current list in the Asset Modeling docs before designing around a specific type. +- Mandatory fields must be filled before an upload or save can finish. Use them sparingly so uploads are not blocked on optional information. +- Edit metadata for an individual asset in the configurable metadata panel. + +### AI tags, alt text and colors + +- In the metadata panel, **Suggest Tags with AI** and **Suggest Description with AI** generate suggestions. AI can also extract dominant colors, which powers color-based filtering. Suggestions can be wrong, so review them before saving. +- **Auto-populate at upload** is configured in Space Settings > AI Settings. Enable the AI Tags and Alt Text toggles, set Advanced Properties, and click Save Properties. + - Applies to images and to new uploads only. Existing assets are not enriched, and replacing a file does not trigger it. + - Values are written into version 1. No extra version is created, nothing waits for review, and uploads are not slowed down. + - It never overwrites a value the uploader entered. It only fills empty destinations. + - Tags: up to 10 per asset. Confidence ranges from 10% to 100%, and the default is 10 tags at 80%. Tagging adds tags and never removes existing ones. + - Alt text is English only. It goes to the system Description field or to one single-line textbox field you choose. It is skipped if the destination already has a value, or if the chosen field is missing from the asset's type or was deleted or changed type. Tags are still written in those cases. + +### Duplicate management + +- Detects **exact duplicates** (byte-identical images). Two or more form a **duplicate set**, and no copy is treated as the original. +- Images only, and a set cannot span workspaces. Detection is on by default in every workspace and runs in the background after upload, replace, delete and restore. It does not block or flag uploads. +- An admin with permission to edit space settings can turn it off per workspace. +- Open it from the asset listing: More Actions > Duplicate Management. Resolve a set by **Keep This, Delete the Rest**, by deleting a single copy, or by bulk-deleting the duplicates. +- Gotchas to state up front: + - Resized, cropped, re-exported or recompressed copies are not detected. + - Duplicate sets cannot be searched, filtered or sorted. + - Users with partial view permission see a partial count. + - Selecting every copy deletes the image, with no warning. + - Deleting a copy removes it everywhere it is used or linked, so check references first. + - A set disappears once fewer than two images remain, and new duplicates can take a moment to appear. + +### Versions + +- Any change to the file or to metadata creates a new version, and so does a Save Assets action. Default names are Version 1, Version 2 and so on. +- Rename a version from the version selector at the top right. The name can be up to 32 characters using letters, numbers, spaces, hyphens and underscores. Renaming does not create a version. +- To restore an earlier version, select it in the version selector and click **Save Asset**. It becomes the latest version, and the older versions stay in history. +- Only users with edit permission can rename or restore. Others can view history. +- Do not mix this with the CMS asset library's History > View flow. They are different products. + +### Trash and restore + +- Deleted assets and folders go to **Trash** (Space Settings > Trash) and can be restored within **14 days** of deletion. After that they are permanently removed. +- Restore with the ⋮ menu > Restore. Managing assets in the workspace is required. Trash can be filtered by who deleted, type and date range. +- For folders, choose **Restore With Assets** or **Restore without Assets**. With Assets restores only the assets that were in the folder when it was deleted. Assets deleted earlier stay in trash. +- If Restore is greyed out, the parent folder is still in trash. Restore the folder first. +- Deleting an asset removes it from entries that use it. Advise checking references before deleting. + +### Visual markups + +- A **visual markup** annotates a region of an image. A **hotspot** is a single point (x and y). A **bounding box** is a rectangle (x, y, width, height). +- Each markup needs a title. Description, URL and position are optional. Typical uses are shoppable images, annotated diagrams and linking related content. +- **Suggest Markup with AI** proposes bounding boxes with confidence scores. Review them before saving. +- Per markup you can edit, duplicate, hide or delete. Bulk actions can hide all markups or **delete all markups, which is permanent**. +- Markups are for interactive and shoppable content. Do not describe them as review comments or annotation threads. + +### Image editing + +- The public documentation for editing images inside Assets is limited. Describe only what the user's current docs confirm, and point them to the Assets docs for the editing options available to them. +- Do not confuse this with delivery-time transformations (crop, fit, orient and so on) in the Image Delivery API, or with the Image Cropper extension. Those belong to the CMS side. + +### CMS integration and delivery + +- Link a space to one or more stacks so its assets can be used in entries. For setup steps, direct the user to the current Assets documentation. +- In the Content Delivery API, the `asset_fields[]` query parameter applies to assets from the new Assets product. Documented values are `visual_markups` and `user_defined_fields`, and the parameter can be repeated. Stack-library assets do not return those keys. +- `visual_markups` is an empty array when an asset has none. A hotspot returns x and y, and a bounding box also returns width and height. +- Do not state CDN host names, URL formats or branch behavior for Assets as fact unless the user's docs confirm them. + +## Output Format + +Be concise and practical. Use the product's terms. Give UI paths as `Menu > Item`. Use short bullets for steps, limits and gotchas. When something is undocumented or uncertain, say so and link to the docs instead of guessing. + +## Tooling Notes + +Read-only advisory skill. Do not upload, move, delete, restore or modify assets, spaces or settings. Explain the steps and let the user perform them. + +References: + +- https://www.contentstack.com/docs/assets/about-assets +- https://www.contentstack.com/docs/assets/about-spaces-and-workspaces +- https://www.contentstack.com/docs/assets/about-asset-modeling +- https://www.contentstack.com/docs/assets/enhance-asset-management-with-ai +- https://www.contentstack.com/docs/assets/manage-duplicate-images +- https://www.contentstack.com/docs/assets/asset-versioning +- https://www.contentstack.com/docs/assets/restore-an-asset-or-folder +- https://www.contentstack.com/docs/assets/add-visual-markups +- https://www.contentstack.com/docs/developers/apis/content-delivery-api/assets + +## Security + +### Defaults + +- Never expose tokens or API keys. +- Use environment variables for credentials in any example code. + +### Destructive Actions + +Do not perform destructive actions. For deleting a space, deleting duplicates, emptying or letting trash expire, or deleting all markups, explain the consequences and the safe checks (references, restore window, selection), then leave execution to the user. + +### Secrets + +Never reveal management tokens, API keys or other secrets. Reference environment variables only. + +## Product Context + +- Product: Assets (DAM) +- Description: Contentstack Assets is the digital asset management layer: spaces, workspaces, folders, asset types and metadata, AI enrichment, duplicate management, versioning, visual markups and CMS integration. +- Product safety rules: + - Never expose management tokens or API keys. + - Always use environment variables for credentials. + - Treat deletion of spaces, assets and markups as irreversible unless the docs state a restore window. diff --git a/cursor/rules/01-brand-kit-assistant.mdc b/cursor/rules/02-brand-kit-assistant.mdc similarity index 100% rename from cursor/rules/01-brand-kit-assistant.mdc rename to cursor/rules/02-brand-kit-assistant.mdc diff --git a/cursor/rules/02-cms-assets.mdc b/cursor/rules/03-cms-assets.mdc similarity index 100% rename from cursor/rules/02-cms-assets.mdc rename to cursor/rules/03-cms-assets.mdc diff --git a/cursor/rules/03-cms-branches-aliases.mdc b/cursor/rules/04-cms-branches-aliases.mdc similarity index 100% rename from cursor/rules/03-cms-branches-aliases.mdc rename to cursor/rules/04-cms-branches-aliases.mdc diff --git a/cursor/rules/04-cms-data-modeling-best-practices.mdc b/cursor/rules/05-cms-data-modeling-best-practices.mdc similarity index 100% rename from cursor/rules/04-cms-data-modeling-best-practices.mdc rename to cursor/rules/05-cms-data-modeling-best-practices.mdc diff --git a/cursor/rules/05-cms-entries.mdc b/cursor/rules/06-cms-entries.mdc similarity index 100% rename from cursor/rules/05-cms-entries.mdc rename to cursor/rules/06-cms-entries.mdc diff --git a/cursor/rules/06-cms-environments-publishing.mdc b/cursor/rules/07-cms-environments-publishing.mdc similarity index 100% rename from cursor/rules/06-cms-environments-publishing.mdc rename to cursor/rules/07-cms-environments-publishing.mdc diff --git a/cursor/rules/07-cms-live-preview-visual-builder-support-assistant.mdc b/cursor/rules/08-cms-live-preview-visual-builder-support-assistant.mdc similarity index 100% rename from cursor/rules/07-cms-live-preview-visual-builder-support-assistant.mdc rename to cursor/rules/08-cms-live-preview-visual-builder-support-assistant.mdc diff --git a/cursor/rules/08-cms-localization.mdc b/cursor/rules/09-cms-localization.mdc similarity index 100% rename from cursor/rules/08-cms-localization.mdc rename to cursor/rules/09-cms-localization.mdc diff --git a/cursor/rules/09-cms-releases.mdc b/cursor/rules/10-cms-releases.mdc similarity index 100% rename from cursor/rules/09-cms-releases.mdc rename to cursor/rules/10-cms-releases.mdc diff --git a/cursor/rules/10-cms-roles-permissions.mdc b/cursor/rules/11-cms-roles-permissions.mdc similarity index 100% rename from cursor/rules/10-cms-roles-permissions.mdc rename to cursor/rules/11-cms-roles-permissions.mdc diff --git a/cursor/rules/11-cms-taxonomy.mdc b/cursor/rules/12-cms-taxonomy.mdc similarity index 100% rename from cursor/rules/11-cms-taxonomy.mdc rename to cursor/rules/12-cms-taxonomy.mdc diff --git a/cursor/rules/12-cms-tokens-authentication.mdc b/cursor/rules/13-cms-tokens-authentication.mdc similarity index 100% rename from cursor/rules/12-cms-tokens-authentication.mdc rename to cursor/rules/13-cms-tokens-authentication.mdc diff --git a/cursor/rules/13-cms-variants-personalization.mdc b/cursor/rules/14-cms-variants-personalization.mdc similarity index 100% rename from cursor/rules/13-cms-variants-personalization.mdc rename to cursor/rules/14-cms-variants-personalization.mdc diff --git a/cursor/rules/14-cms-webhooks.mdc b/cursor/rules/15-cms-webhooks.mdc similarity index 100% rename from cursor/rules/14-cms-webhooks.mdc rename to cursor/rules/15-cms-webhooks.mdc diff --git a/cursor/rules/15-cms-workflows.mdc b/cursor/rules/16-cms-workflows.mdc similarity index 100% rename from cursor/rules/15-cms-workflows.mdc rename to cursor/rules/16-cms-workflows.mdc diff --git a/cursor/rules/16-developer-hub-app-architect.mdc b/cursor/rules/17-developer-hub-app-architect.mdc similarity index 100% rename from cursor/rules/16-developer-hub-app-architect.mdc rename to cursor/rules/17-developer-hub-app-architect.mdc diff --git a/cursor/rules/17-dx-delivery-sdk.mdc b/cursor/rules/18-dx-delivery-sdk.mdc similarity index 100% rename from cursor/rules/17-dx-delivery-sdk.mdc rename to cursor/rules/18-dx-delivery-sdk.mdc diff --git a/cursor/rules/18-dx-migrate-js-to-ts-sdk.mdc b/cursor/rules/19-dx-migrate-js-to-ts-sdk.mdc similarity index 100% rename from cursor/rules/18-dx-migrate-js-to-ts-sdk.mdc rename to cursor/rules/19-dx-migrate-js-to-ts-sdk.mdc diff --git a/cursor/rules/19-launch-sync-environment-variables-from-env-example.mdc b/cursor/rules/20-launch-sync-environment-variables-from-env-example.mdc similarity index 100% rename from cursor/rules/19-launch-sync-environment-variables-from-env-example.mdc rename to cursor/rules/20-launch-sync-environment-variables-from-env-example.mdc diff --git a/cursor/rules/20-launch-trigger-and-monitor-launch-deployments.mdc b/cursor/rules/21-launch-trigger-and-monitor-launch-deployments.mdc similarity index 100% rename from cursor/rules/20-launch-trigger-and-monitor-launch-deployments.mdc rename to cursor/rules/21-launch-trigger-and-monitor-launch-deployments.mdc diff --git a/cursor/rules/21-migration-companion.mdc b/cursor/rules/22-migration-companion.mdc similarity index 100% rename from cursor/rules/21-migration-companion.mdc rename to cursor/rules/22-migration-companion.mdc diff --git a/manifest.json b/manifest.json index 564e68e..0490a9e 100644 --- a/manifest.json +++ b/manifest.json @@ -1,7 +1,12 @@ { "exported_at": "2026-04-28T08:27:32.000Z", - "skill_count": 21, + "skill_count": 22, "skills": [ + { + "slug": "asset-management", + "title": "Asset Management", + "product": "Assets" + }, { "slug": "brand-kit-assistant", "title": "Brand Kit Assistant", diff --git a/skills/CLAUDE.md b/skills/CLAUDE.md index e86f870..14c88d6 100644 --- a/skills/CLAUDE.md +++ b/skills/CLAUDE.md @@ -11,6 +11,7 @@ Use the table below to route a user request to the right skill. Each row maps a | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) | | Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](./cms-live-preview-visual-builder-support-assistant/SKILL.md) | | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) | +| Use when a user asks about the Contentstack Assets DAM product: spaces and workspaces, folders, asset types and metadata, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, image editing, or linking Assets to CMS stacks. Not for the CMS stack asset library (use cms-assets). | [Asset Management](./asset-management/SKILL.md) | | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](./cms-assets/SKILL.md) | | Use when developers need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. | [Contentstack Taxonomy](./cms-taxonomy/SKILL.md) | | Use when developers ask about workflow stage design, approval processes, publish rules, self-approval prevention, transition restrictions, or automation triggered by workflow changes. | [Workflows & Publish Rules](./cms-workflows/SKILL.md) | diff --git a/skills/asset-management/SKILL.md b/skills/asset-management/SKILL.md new file mode 100644 index 0000000..9aeb0bb --- /dev/null +++ b/skills/asset-management/SKILL.md @@ -0,0 +1,197 @@ +--- +name: asset-management +description: "Advise on Contentstack Assets, the standalone digital asset management (DAM) product. Cover spaces and workspaces, folders, asset types and metadata, AI tagging and alt text, duplicate management, versions, trash and restore, visual markups, image editing, and linking to CMS stacks. Not for the CMS stack asset library; use cms-assets for that." +allowed-tools: Read Grep Glob +--- + +# Asset Management (Contentstack Assets DAM) + +## Description + +Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, image editing, and CMS integration. + +## When to Use + +Use when a user asks about the Contentstack Assets DAM: organizing assets in spaces, workspaces and folders, modeling asset metadata, AI tags and alt text, finding and removing duplicates, versioning, restoring deleted assets, visual markups, or using Assets with a CMS stack. + +Do not use for the CMS stack asset library (stack-level uploads, folders, Image Delivery API, publishing to environments). Route those questions to `cms-assets`. If it is unclear which one the user means, ask whether they work in an Assets space or in the asset library inside a stack. + +## User Problem + +Teams adopting Contentstack Assets need to structure spaces and workspaces sensibly, model metadata so assets are findable, use AI features safely, keep the library free of duplicates, and understand what is and is not recoverable when assets are deleted or replaced. + +## Success Criteria + +- Distinguish the Assets DAM from the CMS asset library. +- Use the product's own terminology: space, workspace, main workspace, asset type, system metadata, user-defined metadata, duplicate set, visual markup. +- State documented behavior and limits accurately, and say plainly when something is not documented. +- Warn about irreversible or hard-to-reverse actions before the user takes them. + +## Expected Inputs + +- Which product the user means (Assets space or CMS stack library) +- Organization shape (brands, regions, teams) and number of spaces +- Asset types and metadata the team needs +- The specific task or problem (duplicates, restore, versions, AI settings, markups) + +## Expected Outputs + +- Space, workspace and folder structure recommendations +- Asset type and metadata modeling guidance +- Step-by-step UI paths for the task +- Gotchas and irreversible-action warnings +- Pointers to the official docs for anything not covered here + +## Example User Requests + +- How should I split my brands and regions across spaces and workspaces? +- How do I add custom fields to my images? +- Can Assets tag my images and write alt text automatically? +- How do I find and remove duplicate images? +- I deleted a folder by mistake. Can I get it back? +- How do I roll back to an earlier version of an asset? +- How do I add hotspots to a product image? +- How do I use assets from a space in my CMS entries? + +## Workflow Summary + +1. Confirm the user means the Assets DAM, not the CMS asset library. +2. Identify the topic: structure, metadata, AI, duplicates, versions, trash, markups, editing, or CMS integration. +3. Answer with documented behavior using the product's terminology. +4. Flag limits and irreversible actions. +5. Link to the relevant docs page for anything undocumented or likely to change. + +## Instructions + +### Spaces and workspaces + +- A **space** is the top-level container, often one per brand, business unit or region. Roles, permissions and settings are governed at the space level, so each space is managed independently. +- A **workspace** is an isolated environment inside a space. Every space has a **main workspace**. New workspaces are created from the main workspace or from another parent workspace, inherit its assets, metadata and configuration, and keep their own changes isolated from the parent. +- A space can be linked to one or more CMS stacks, and assets can be reused across stacks. +- Recommend a small number of spaces and workspaces. Over-fragmenting adds management overhead. +- Space Settings > General holds the title (required) and description. The Space UID is generated by the system and cannot be changed. +- Deleting a space is irreversible. It removes the space's assets, users and collaborators. Always warn before recommending it. +- Duplicate Management is configured per workspace. AI Settings live under Space Settings. + +### Folders + +- Create a folder with **+ New > New Folder**. Name is required and description is optional. Folders appear in the listing and in the Folders section of the Filters panel. +- Recommend a folder structure that matches how teams search, such as by campaign, asset category or brand, and keep it consistent across workspaces. + +### Roles and permissions + +- Access is governed per space through roles, teams and associations. Where the user needs the exact predefined roles or asset-level sharing options, direct them to the current Assets documentation rather than guessing. +- For least privilege, give contributors only the access they need and restrict delete and settings permissions to a few administrators. + +### Asset types and metadata + +- Metadata comes in layers: **system metadata** (read-only: file name, UID, URLs, MIME type, size, created and modified details), **general metadata**, and **user-defined metadata** from custom fields. +- Each **asset type** maps to one MIME type and one file extension. On upload, a matching type applies automatically and its fields appear. System types cover images, audio, video, documents and archives, and you can add custom types. +- User-defined fields are reusable across asset types. Documented field types include single line textbox, multi line textbox, link, select (dropdown, radio buttons or checkboxes), number, date, boolean and group. +- The set of supported field types has been expanding. Tell the user to confirm the current list in the Asset Modeling docs before designing around a specific type. +- Mandatory fields must be filled before an upload or save can finish. Use them sparingly so uploads are not blocked on optional information. +- Edit metadata for an individual asset in the configurable metadata panel. + +### AI tags, alt text and colors + +- In the metadata panel, **Suggest Tags with AI** and **Suggest Description with AI** generate suggestions. AI can also extract dominant colors, which powers color-based filtering. Suggestions can be wrong, so review them before saving. +- **Auto-populate at upload** is configured in Space Settings > AI Settings. Enable the AI Tags and Alt Text toggles, set Advanced Properties, and click Save Properties. + - Applies to images and to new uploads only. Existing assets are not enriched, and replacing a file does not trigger it. + - Values are written into version 1. No extra version is created, nothing waits for review, and uploads are not slowed down. + - It never overwrites a value the uploader entered. It only fills empty destinations. + - Tags: up to 10 per asset. Confidence ranges from 10% to 100%, and the default is 10 tags at 80%. Tagging adds tags and never removes existing ones. + - Alt text is English only. It goes to the system Description field or to one single-line textbox field you choose. It is skipped if the destination already has a value, or if the chosen field is missing from the asset's type or was deleted or changed type. Tags are still written in those cases. + +### Duplicate management + +- Detects **exact duplicates** (byte-identical images). Two or more form a **duplicate set**, and no copy is treated as the original. +- Images only, and a set cannot span workspaces. Detection is on by default in every workspace and runs in the background after upload, replace, delete and restore. It does not block or flag uploads. +- An admin with permission to edit space settings can turn it off per workspace. +- Open it from the asset listing: More Actions > Duplicate Management. Resolve a set by **Keep This, Delete the Rest**, by deleting a single copy, or by bulk-deleting the duplicates. +- Gotchas to state up front: + - Resized, cropped, re-exported or recompressed copies are not detected. + - Duplicate sets cannot be searched, filtered or sorted. + - Users with partial view permission see a partial count. + - Selecting every copy deletes the image, with no warning. + - Deleting a copy removes it everywhere it is used or linked, so check references first. + - A set disappears once fewer than two images remain, and new duplicates can take a moment to appear. + +### Versions + +- Any change to the file or to metadata creates a new version, and so does a Save Assets action. Default names are Version 1, Version 2 and so on. +- Rename a version from the version selector at the top right. The name can be up to 32 characters using letters, numbers, spaces, hyphens and underscores. Renaming does not create a version. +- To restore an earlier version, select it in the version selector and click **Save Asset**. It becomes the latest version, and the older versions stay in history. +- Only users with edit permission can rename or restore. Others can view history. +- Do not mix this with the CMS asset library's History > View flow. They are different products. + +### Trash and restore + +- Deleted assets and folders go to **Trash** (Space Settings > Trash) and can be restored within **14 days** of deletion. After that they are permanently removed. +- Restore with the ⋮ menu > Restore. Managing assets in the workspace is required. Trash can be filtered by who deleted, type and date range. +- For folders, choose **Restore With Assets** or **Restore without Assets**. With Assets restores only the assets that were in the folder when it was deleted. Assets deleted earlier stay in trash. +- If Restore is greyed out, the parent folder is still in trash. Restore the folder first. +- Deleting an asset removes it from entries that use it. Advise checking references before deleting. + +### Visual markups + +- A **visual markup** annotates a region of an image. A **hotspot** is a single point (x and y). A **bounding box** is a rectangle (x, y, width, height). +- Each markup needs a title. Description, URL and position are optional. Typical uses are shoppable images, annotated diagrams and linking related content. +- **Suggest Markup with AI** proposes bounding boxes with confidence scores. Review them before saving. +- Per markup you can edit, duplicate, hide or delete. Bulk actions can hide all markups or **delete all markups, which is permanent**. +- Markups are for interactive and shoppable content. Do not describe them as review comments or annotation threads. + +### Image editing + +- The public documentation for editing images inside Assets is limited. Describe only what the user's current docs confirm, and point them to the Assets docs for the editing options available to them. +- Do not confuse this with delivery-time transformations (crop, fit, orient and so on) in the Image Delivery API, or with the Image Cropper extension. Those belong to the CMS side. + +### CMS integration and delivery + +- Link a space to one or more stacks so its assets can be used in entries. For setup steps, direct the user to the current Assets documentation. +- In the Content Delivery API, the `asset_fields[]` query parameter applies to assets from the new Assets product. Documented values are `visual_markups` and `user_defined_fields`, and the parameter can be repeated. Stack-library assets do not return those keys. +- `visual_markups` is an empty array when an asset has none. A hotspot returns x and y, and a bounding box also returns width and height. +- Do not state CDN host names, URL formats or branch behavior for Assets as fact unless the user's docs confirm them. + +## Output Format + +Be concise and practical. Use the product's terms. Give UI paths as `Menu > Item`. Use short bullets for steps, limits and gotchas. When something is undocumented or uncertain, say so and link to the docs instead of guessing. + +## Tooling Notes + +Read-only advisory skill. Do not upload, move, delete, restore or modify assets, spaces or settings. Explain the steps and let the user perform them. + +References: + +- https://www.contentstack.com/docs/assets/about-assets +- https://www.contentstack.com/docs/assets/about-spaces-and-workspaces +- https://www.contentstack.com/docs/assets/about-asset-modeling +- https://www.contentstack.com/docs/assets/enhance-asset-management-with-ai +- https://www.contentstack.com/docs/assets/manage-duplicate-images +- https://www.contentstack.com/docs/assets/asset-versioning +- https://www.contentstack.com/docs/assets/restore-an-asset-or-folder +- https://www.contentstack.com/docs/assets/add-visual-markups +- https://www.contentstack.com/docs/developers/apis/content-delivery-api/assets + +## Security + +### Defaults + +- Never expose tokens or API keys. +- Use environment variables for credentials in any example code. + +### Destructive Actions + +Do not perform destructive actions. For deleting a space, deleting duplicates, emptying or letting trash expire, or deleting all markups, explain the consequences and the safe checks (references, restore window, selection), then leave execution to the user. + +### Secrets + +Never reveal management tokens, API keys or other secrets. Reference environment variables only. + +## Product Context + +- Product: Assets (DAM) +- Description: Contentstack Assets is the digital asset management layer: spaces, workspaces, folders, asset types and metadata, AI enrichment, duplicate management, versioning, visual markups and CMS integration. +- Product safety rules: + - Never expose management tokens or API keys. + - Always use environment variables for credentials. + - Treat deletion of spaces, assets and markups as irreversible unless the docs state a restore window. From 85a22fcc2e6573d1b89423531725a2ee588c530a Mon Sep 17 00:00:00 2001 From: Mun-GitHub Date: Mon, 12 Oct 2026 20:54:42 +0530 Subject: [PATCH 2/8] feat(skills): refine asset-management skill Remove image editing section, restrict user-defined field types to single line text, number, select and group, and add localization and saved views guidance. Regenerated cursor rules and codex tree. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 2 +- codex/AGENTS.md | 2 +- codex/asset-management/SKILL.md | 21 +++++++++++++-------- cursor/rules/00-router.mdc | 2 +- cursor/rules/01-asset-management.mdc | 23 ++++++++++++++--------- skills/CLAUDE.md | 2 +- skills/asset-management/SKILL.md | 23 ++++++++++++++--------- 7 files changed, 45 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 8a190c2..324d3fd 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ npx skills add @ | Slug | Title | Product | What it helps with | | --- | --- | --- | --- | -| `asset-management` | Asset Management | Assets | Assets DAM spaces and workspaces, folders, asset types and metadata, AI tagging and alt text, duplicate management, versions, trash and restore, visual markups, and CMS integration. | +| `asset-management` | Asset Management | Assets | Assets DAM spaces and workspaces, folders, asset types and metadata, localization, saved views, AI tagging and alt text, duplicate management, versions, trash and restore, visual markups, and CMS integration. | | `brand-kit-assistant` | Brand Kit Assistant | Brand Kit | Brand Kit concepts, setup, governance, Voice Profiles, Knowledge Vault, on-brand AI generation, and API-task routing. | | `cms-assets` | Contentstack Assets | CMS | Asset organization, image transformations, publishing lifecycle, CDN behavior, and asset limits. | | `cms-branches-aliases` | Branches & Aliases | CMS | Isolated content development, alias-based deployments, CI/CD integration, merge behavior, and rollback patterns. | diff --git a/codex/AGENTS.md b/codex/AGENTS.md index 14c88d6..bb93d1f 100644 --- a/codex/AGENTS.md +++ b/codex/AGENTS.md @@ -11,7 +11,7 @@ Use the table below to route a user request to the right skill. Each row maps a | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) | | Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](./cms-live-preview-visual-builder-support-assistant/SKILL.md) | | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) | -| Use when a user asks about the Contentstack Assets DAM product: spaces and workspaces, folders, asset types and metadata, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, image editing, or linking Assets to CMS stacks. Not for the CMS stack asset library (use cms-assets). | [Asset Management](./asset-management/SKILL.md) | +| Use when a user asks about the Contentstack Assets DAM product: spaces and workspaces, folders, asset types and metadata, localization, saved views, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, or linking Assets to CMS stacks. Not for the CMS stack asset library (use cms-assets). | [Asset Management](./asset-management/SKILL.md) | | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](./cms-assets/SKILL.md) | | Use when developers need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. | [Contentstack Taxonomy](./cms-taxonomy/SKILL.md) | | Use when developers ask about workflow stage design, approval processes, publish rules, self-approval prevention, transition restrictions, or automation triggered by workflow changes. | [Workflows & Publish Rules](./cms-workflows/SKILL.md) | diff --git a/codex/asset-management/SKILL.md b/codex/asset-management/SKILL.md index 6f3ae2a..d8fd2fd 100644 --- a/codex/asset-management/SKILL.md +++ b/codex/asset-management/SKILL.md @@ -5,7 +5,7 @@ ## Description -Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, image editing, and CMS integration. +Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, localization, filters and saved views, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, and CMS integration. ## When to Use @@ -43,6 +43,8 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - How should I split my brands and regions across spaces and workspaces? - How do I add custom fields to my images? +- How do I add a language to a workspace? +- Can I save a set of filters and reuse it? - Can Assets tag my images and write alt text automatically? - How do I find and remove duplicate images? - I deleted a folder by mistake. Can I get it back? @@ -84,10 +86,18 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - Metadata comes in layers: **system metadata** (read-only: file name, UID, URLs, MIME type, size, created and modified details), **general metadata**, and **user-defined metadata** from custom fields. - Each **asset type** maps to one MIME type and one file extension. On upload, a matching type applies automatically and its fields appear. System types cover images, audio, video, documents and archives, and you can add custom types. -- User-defined fields are reusable across asset types. Documented field types include single line textbox, multi line textbox, link, select (dropdown, radio buttons or checkboxes), number, date, boolean and group. -- The set of supported field types has been expanding. Tell the user to confirm the current list in the Asset Modeling docs before designing around a specific type. +- User-defined fields are reusable across asset types. The supported field types are single line text, number, select and group. Do not suggest other types, such as multi line text, date, boolean or link. - Mandatory fields must be filled before an upload or save can finish. Use them sparingly so uploads are not blocked on optional information. - Edit metadata for an individual asset in the configurable metadata panel. +- **Filters and saved views:** User-defined fields can be used as filters when browsing assets, so well-modeled fields make the library searchable. A filter combination can be saved as a **saved view** and reused later instead of rebuilding the filters each time. Advise modeling fields with filtering in mind, for example a select field for campaign or usage rights. + +### Localization + +- Assets supports localized asset versions within a space. +- Adding a language is a two-step process: + 1. Add the language in product settings. + 2. Add it to each workspace that needs it: **Space Settings > Workspaces >** pick the workspace **> Manage Locales**. +- Locales are enabled per workspace, so a language added in product settings does not appear in a workspace until it is added there. ### AI tags, alt text and colors @@ -137,11 +147,6 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - Per markup you can edit, duplicate, hide or delete. Bulk actions can hide all markups or **delete all markups, which is permanent**. - Markups are for interactive and shoppable content. Do not describe them as review comments or annotation threads. -### Image editing - -- The public documentation for editing images inside Assets is limited. Describe only what the user's current docs confirm, and point them to the Assets docs for the editing options available to them. -- Do not confuse this with delivery-time transformations (crop, fit, orient and so on) in the Image Delivery API, or with the Image Cropper extension. Those belong to the CMS side. - ### CMS integration and delivery - Link a space to one or more stacks so its assets can be used in entries. For setup steps, direct the user to the current Assets documentation. diff --git a/cursor/rules/00-router.mdc b/cursor/rules/00-router.mdc index 8cc602e..41d5221 100644 --- a/cursor/rules/00-router.mdc +++ b/cursor/rules/00-router.mdc @@ -16,7 +16,7 @@ Use the table below to route a user request to the right skill. Each row maps a | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](../../skills/cms-data-modeling-best-practices/SKILL.md) | | Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](../../skills/cms-live-preview-visual-builder-support-assistant/SKILL.md) | | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](../../skills/cms-entries/SKILL.md) | -| Use when a user asks about the Contentstack Assets DAM product: spaces and workspaces, folders, asset types and metadata, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, image editing, or linking Assets to CMS stacks. Not for the CMS stack asset library (use cms-assets). | [Asset Management](../../skills/asset-management/SKILL.md) | +| Use when a user asks about the Contentstack Assets DAM product: spaces and workspaces, folders, asset types and metadata, localization, saved views, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, or linking Assets to CMS stacks. Not for the CMS stack asset library (use cms-assets). | [Asset Management](../../skills/asset-management/SKILL.md) | | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](../../skills/cms-assets/SKILL.md) | | Use when developers need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. | [Contentstack Taxonomy](../../skills/cms-taxonomy/SKILL.md) | | Use when developers ask about workflow stage design, approval processes, publish rules, self-approval prevention, transition restrictions, or automation triggered by workflow changes. | [Workflows & Publish Rules](../../skills/cms-workflows/SKILL.md) | diff --git a/cursor/rules/01-asset-management.mdc b/cursor/rules/01-asset-management.mdc index ca09876..d6aeab7 100644 --- a/cursor/rules/01-asset-management.mdc +++ b/cursor/rules/01-asset-management.mdc @@ -1,5 +1,5 @@ --- -description: "Advise on Contentstack Assets, the standalone digital asset management (DAM) product. Cover spaces and workspaces, folders, asset types and metadata, AI tagging and alt text, duplicate management, versions, trash and restore, visual markups, image editing, and linking to CMS stacks. Not for the CMS stack asset library; use cms-assets for that." +description: "Advise on Contentstack Assets, the standalone digital asset management (DAM) product. Cover spaces and workspaces, folders, asset types and metadata, localization, saved views, AI tagging and alt text, duplicate management, versions, trash and restore, visual markups, and linking to CMS stacks. Not for the CMS stack asset library; use cms-assets for that." alwaysApply: false --- @@ -8,7 +8,7 @@ alwaysApply: false ## Description -Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, image editing, and CMS integration. +Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, localization, filters and saved views, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, and CMS integration. ## When to Use @@ -46,6 +46,8 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - How should I split my brands and regions across spaces and workspaces? - How do I add custom fields to my images? +- How do I add a language to a workspace? +- Can I save a set of filters and reuse it? - Can Assets tag my images and write alt text automatically? - How do I find and remove duplicate images? - I deleted a folder by mistake. Can I get it back? @@ -87,10 +89,18 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - Metadata comes in layers: **system metadata** (read-only: file name, UID, URLs, MIME type, size, created and modified details), **general metadata**, and **user-defined metadata** from custom fields. - Each **asset type** maps to one MIME type and one file extension. On upload, a matching type applies automatically and its fields appear. System types cover images, audio, video, documents and archives, and you can add custom types. -- User-defined fields are reusable across asset types. Documented field types include single line textbox, multi line textbox, link, select (dropdown, radio buttons or checkboxes), number, date, boolean and group. -- The set of supported field types has been expanding. Tell the user to confirm the current list in the Asset Modeling docs before designing around a specific type. +- User-defined fields are reusable across asset types. The supported field types are single line text, number, select and group. Do not suggest other types, such as multi line text, date, boolean or link. - Mandatory fields must be filled before an upload or save can finish. Use them sparingly so uploads are not blocked on optional information. - Edit metadata for an individual asset in the configurable metadata panel. +- **Filters and saved views:** User-defined fields can be used as filters when browsing assets, so well-modeled fields make the library searchable. A filter combination can be saved as a **saved view** and reused later instead of rebuilding the filters each time. Advise modeling fields with filtering in mind, for example a select field for campaign or usage rights. + +### Localization + +- Assets supports localized asset versions within a space. +- Adding a language is a two-step process: + 1. Add the language in product settings. + 2. Add it to each workspace that needs it: **Space Settings > Workspaces >** pick the workspace **> Manage Locales**. +- Locales are enabled per workspace, so a language added in product settings does not appear in a workspace until it is added there. ### AI tags, alt text and colors @@ -140,11 +150,6 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - Per markup you can edit, duplicate, hide or delete. Bulk actions can hide all markups or **delete all markups, which is permanent**. - Markups are for interactive and shoppable content. Do not describe them as review comments or annotation threads. -### Image editing - -- The public documentation for editing images inside Assets is limited. Describe only what the user's current docs confirm, and point them to the Assets docs for the editing options available to them. -- Do not confuse this with delivery-time transformations (crop, fit, orient and so on) in the Image Delivery API, or with the Image Cropper extension. Those belong to the CMS side. - ### CMS integration and delivery - Link a space to one or more stacks so its assets can be used in entries. For setup steps, direct the user to the current Assets documentation. diff --git a/skills/CLAUDE.md b/skills/CLAUDE.md index 14c88d6..bb93d1f 100644 --- a/skills/CLAUDE.md +++ b/skills/CLAUDE.md @@ -11,7 +11,7 @@ Use the table below to route a user request to the right skill. Each row maps a | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) | | Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](./cms-live-preview-visual-builder-support-assistant/SKILL.md) | | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) | -| Use when a user asks about the Contentstack Assets DAM product: spaces and workspaces, folders, asset types and metadata, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, image editing, or linking Assets to CMS stacks. Not for the CMS stack asset library (use cms-assets). | [Asset Management](./asset-management/SKILL.md) | +| Use when a user asks about the Contentstack Assets DAM product: spaces and workspaces, folders, asset types and metadata, localization, saved views, AI tags and alt text, duplicate management, versions, trash and restore, visual markups, or linking Assets to CMS stacks. Not for the CMS stack asset library (use cms-assets). | [Asset Management](./asset-management/SKILL.md) | | Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. | [Contentstack Assets](./cms-assets/SKILL.md) | | Use when developers need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. | [Contentstack Taxonomy](./cms-taxonomy/SKILL.md) | | Use when developers ask about workflow stage design, approval processes, publish rules, self-approval prevention, transition restrictions, or automation triggered by workflow changes. | [Workflows & Publish Rules](./cms-workflows/SKILL.md) | diff --git a/skills/asset-management/SKILL.md b/skills/asset-management/SKILL.md index 9aeb0bb..d187e30 100644 --- a/skills/asset-management/SKILL.md +++ b/skills/asset-management/SKILL.md @@ -1,6 +1,6 @@ --- name: asset-management -description: "Advise on Contentstack Assets, the standalone digital asset management (DAM) product. Cover spaces and workspaces, folders, asset types and metadata, AI tagging and alt text, duplicate management, versions, trash and restore, visual markups, image editing, and linking to CMS stacks. Not for the CMS stack asset library; use cms-assets for that." +description: "Advise on Contentstack Assets, the standalone digital asset management (DAM) product. Cover spaces and workspaces, folders, asset types and metadata, localization, saved views, AI tagging and alt text, duplicate management, versions, trash and restore, visual markups, and linking to CMS stacks. Not for the CMS stack asset library; use cms-assets for that." allowed-tools: Read Grep Glob --- @@ -8,7 +8,7 @@ allowed-tools: Read Grep Glob ## Description -Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, image editing, and CMS integration. +Advise on Contentstack Assets, the standalone DAM product (also called "Asset Management" in some docs). Cover spaces and workspaces, folders, roles, asset types and metadata, localization, filters and saved views, AI-assisted metadata, duplicate management, versions, trash and restore, visual markups, and CMS integration. ## When to Use @@ -46,6 +46,8 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - How should I split my brands and regions across spaces and workspaces? - How do I add custom fields to my images? +- How do I add a language to a workspace? +- Can I save a set of filters and reuse it? - Can Assets tag my images and write alt text automatically? - How do I find and remove duplicate images? - I deleted a folder by mistake. Can I get it back? @@ -87,10 +89,18 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - Metadata comes in layers: **system metadata** (read-only: file name, UID, URLs, MIME type, size, created and modified details), **general metadata**, and **user-defined metadata** from custom fields. - Each **asset type** maps to one MIME type and one file extension. On upload, a matching type applies automatically and its fields appear. System types cover images, audio, video, documents and archives, and you can add custom types. -- User-defined fields are reusable across asset types. Documented field types include single line textbox, multi line textbox, link, select (dropdown, radio buttons or checkboxes), number, date, boolean and group. -- The set of supported field types has been expanding. Tell the user to confirm the current list in the Asset Modeling docs before designing around a specific type. +- User-defined fields are reusable across asset types. The supported field types are single line text, number, select and group. Do not suggest other types, such as multi line text, date, boolean or link. - Mandatory fields must be filled before an upload or save can finish. Use them sparingly so uploads are not blocked on optional information. - Edit metadata for an individual asset in the configurable metadata panel. +- **Filters and saved views:** User-defined fields can be used as filters when browsing assets, so well-modeled fields make the library searchable. A filter combination can be saved as a **saved view** and reused later instead of rebuilding the filters each time. Advise modeling fields with filtering in mind, for example a select field for campaign or usage rights. + +### Localization + +- Assets supports localized asset versions within a space. +- Adding a language is a two-step process: + 1. Add the language in product settings. + 2. Add it to each workspace that needs it: **Space Settings > Workspaces >** pick the workspace **> Manage Locales**. +- Locales are enabled per workspace, so a language added in product settings does not appear in a workspace until it is added there. ### AI tags, alt text and colors @@ -140,11 +150,6 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - Per markup you can edit, duplicate, hide or delete. Bulk actions can hide all markups or **delete all markups, which is permanent**. - Markups are for interactive and shoppable content. Do not describe them as review comments or annotation threads. -### Image editing - -- The public documentation for editing images inside Assets is limited. Describe only what the user's current docs confirm, and point them to the Assets docs for the editing options available to them. -- Do not confuse this with delivery-time transformations (crop, fit, orient and so on) in the Image Delivery API, or with the Image Cropper extension. Those belong to the CMS side. - ### CMS integration and delivery - Link a space to one or more stacks so its assets can be used in entries. For setup steps, direct the user to the current Assets documentation. From 72e4c595aaefb070e3b4613bc88bd76f71fd5c29 Mon Sep 17 00:00:00 2001 From: Mun-GitHub Date: Mon, 19 Oct 2026 21:26:56 +0530 Subject: [PATCH 3/8] feat(skills): add user-defined field search guidance to asset-management Co-Authored-By: Claude Sonnet 5.5 --- codex/asset-management/SKILL.md | 24 ++++++++++++++++++++++++ cursor/rules/01-asset-management.mdc | 24 ++++++++++++++++++++++++ skills/asset-management/SKILL.md | 24 ++++++++++++++++++++++++ 3 files changed, 72 insertions(+) diff --git a/codex/asset-management/SKILL.md b/codex/asset-management/SKILL.md index d8fd2fd..727e9e4 100644 --- a/codex/asset-management/SKILL.md +++ b/codex/asset-management/SKILL.md @@ -45,6 +45,7 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - How do I add custom fields to my images? - How do I add a language to a workspace? - Can I save a set of filters and reuse it? +- How do I search assets by a custom field value? - Can Assets tag my images and write alt text automatically? - How do I find and remove duplicate images? - I deleted a folder by mistake. Can I get it back? @@ -99,6 +100,29 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi 2. Add it to each workspace that needs it: **Space Settings > Workspaces >** pick the workspace **> Manage Locales**. - Locales are enabled per workspace, so a language added in product settings does not appear in a workspace until it is added there. +### Filtering assets by user-defined fields + +- To filter by a user-defined field in the Assets search API, send the condition in `query` and use the field's full path: `user_defined_fields..`. Wrap conditions in `$and` or `$or` to combine them. +- Every value must be an operator object, not a plain value. Supported operators are `$eq`, `$ne`, `$in`, `$nin`, `$contains`, `$lt`, `$lte`, `$gt`, `$gte`, `$exists`, `$range` and `$not`. `$regex` is not supported. +- Each entry in `spaces` needs both a `space_uid` and a `workspace` string, for example `"main"`. +- `search_field` only accepts `all`, `title`, `name`, `url` or `category`. It can't target user-defined fields, so use `query` for those. + +Example request body: + +```json +{ + "query": { + "$and": [ + { "user_defined_fields.asset_rights.license_type": { "$eq": "Creative Commons" } } + ] + }, + "limit": 50, + "spaces": [{ "space_uid": "", "workspace": "main" }] +} +``` + +- Check the response body for errors after every search. Don't rely on the HTTP status alone to tell whether a request was valid. + ### AI tags, alt text and colors - In the metadata panel, **Suggest Tags with AI** and **Suggest Description with AI** generate suggestions. AI can also extract dominant colors, which powers color-based filtering. Suggestions can be wrong, so review them before saving. diff --git a/cursor/rules/01-asset-management.mdc b/cursor/rules/01-asset-management.mdc index d6aeab7..cd12300 100644 --- a/cursor/rules/01-asset-management.mdc +++ b/cursor/rules/01-asset-management.mdc @@ -48,6 +48,7 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - How do I add custom fields to my images? - How do I add a language to a workspace? - Can I save a set of filters and reuse it? +- How do I search assets by a custom field value? - Can Assets tag my images and write alt text automatically? - How do I find and remove duplicate images? - I deleted a folder by mistake. Can I get it back? @@ -102,6 +103,29 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi 2. Add it to each workspace that needs it: **Space Settings > Workspaces >** pick the workspace **> Manage Locales**. - Locales are enabled per workspace, so a language added in product settings does not appear in a workspace until it is added there. +### Filtering assets by user-defined fields + +- To filter by a user-defined field in the Assets search API, send the condition in `query` and use the field's full path: `user_defined_fields..`. Wrap conditions in `$and` or `$or` to combine them. +- Every value must be an operator object, not a plain value. Supported operators are `$eq`, `$ne`, `$in`, `$nin`, `$contains`, `$lt`, `$lte`, `$gt`, `$gte`, `$exists`, `$range` and `$not`. `$regex` is not supported. +- Each entry in `spaces` needs both a `space_uid` and a `workspace` string, for example `"main"`. +- `search_field` only accepts `all`, `title`, `name`, `url` or `category`. It can't target user-defined fields, so use `query` for those. + +Example request body: + +```json +{ + "query": { + "$and": [ + { "user_defined_fields.asset_rights.license_type": { "$eq": "Creative Commons" } } + ] + }, + "limit": 50, + "spaces": [{ "space_uid": "", "workspace": "main" }] +} +``` + +- Check the response body for errors after every search. Don't rely on the HTTP status alone to tell whether a request was valid. + ### AI tags, alt text and colors - In the metadata panel, **Suggest Tags with AI** and **Suggest Description with AI** generate suggestions. AI can also extract dominant colors, which powers color-based filtering. Suggestions can be wrong, so review them before saving. diff --git a/skills/asset-management/SKILL.md b/skills/asset-management/SKILL.md index d187e30..e16ffb7 100644 --- a/skills/asset-management/SKILL.md +++ b/skills/asset-management/SKILL.md @@ -48,6 +48,7 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - How do I add custom fields to my images? - How do I add a language to a workspace? - Can I save a set of filters and reuse it? +- How do I search assets by a custom field value? - Can Assets tag my images and write alt text automatically? - How do I find and remove duplicate images? - I deleted a folder by mistake. Can I get it back? @@ -102,6 +103,29 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi 2. Add it to each workspace that needs it: **Space Settings > Workspaces >** pick the workspace **> Manage Locales**. - Locales are enabled per workspace, so a language added in product settings does not appear in a workspace until it is added there. +### Filtering assets by user-defined fields + +- To filter by a user-defined field in the Assets search API, send the condition in `query` and use the field's full path: `user_defined_fields..`. Wrap conditions in `$and` or `$or` to combine them. +- Every value must be an operator object, not a plain value. Supported operators are `$eq`, `$ne`, `$in`, `$nin`, `$contains`, `$lt`, `$lte`, `$gt`, `$gte`, `$exists`, `$range` and `$not`. `$regex` is not supported. +- Each entry in `spaces` needs both a `space_uid` and a `workspace` string, for example `"main"`. +- `search_field` only accepts `all`, `title`, `name`, `url` or `category`. It can't target user-defined fields, so use `query` for those. + +Example request body: + +```json +{ + "query": { + "$and": [ + { "user_defined_fields.asset_rights.license_type": { "$eq": "Creative Commons" } } + ] + }, + "limit": 50, + "spaces": [{ "space_uid": "", "workspace": "main" }] +} +``` + +- Check the response body for errors after every search. Don't rely on the HTTP status alone to tell whether a request was valid. + ### AI tags, alt text and colors - In the metadata panel, **Suggest Tags with AI** and **Suggest Description with AI** generate suggestions. AI can also extract dominant colors, which powers color-based filtering. Suggestions can be wrong, so review them before saving. From 48893917c0d78f18c03b0d406375d8d40862c535 Mon Sep 17 00:00:00 2001 From: Mun-GitHub Date: Mon, 19 Oct 2026 21:35:18 +0530 Subject: [PATCH 4/8] docs: update skill count to 24 --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index ec8d7a2..0503fa8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -50,7 +50,7 @@ Every skill is written once in the open [Agent Skills](https://agentskills.io) f | | | | ------------------------ | -------------------------------------------------------------------------------------------------------------- | -| **Skills included** | 23 (see the [skill reference](skills/index.md)) | +| **Skills included** | 24 (see the [skill reference](skills/index.md)) | | **Products covered** | CMS, Assets, Developer Experience, Studio, Launch, Brand Kit, Developer Hub | | **Supported tools** | Claude Code, claude.ai / Cowork, Cursor, Codex, GitHub Copilot, Gemini CLI, `skills` CLI | | **Source of truth** | `skills//SKILL.md` | From 518945dab0415cb3f1c60b4a89848dea8a4283be Mon Sep 17 00:00:00 2001 From: Mun-GitHub Date: Tue, 20 Oct 2026 14:11:06 +0530 Subject: [PATCH 5/8] Address review: document public search endpoint, soften field types, fix docs and routing - Rewrite the search section against the public Assets API search page (host, path, headers, search_field values, query operators) - Say 'currently supported' for user-defined field types - Add asset-management to docs/overview/introduction.md and docs/how-it-works/router.md; fix product count - Point cms-assets at asset-management for DAM questions - Remove leftover 'editing' from the workflow summary Co-Authored-By: Claude Sonnet 5.5 --- docs/how-it-works/router.md | 3 ++- docs/overview/introduction.md | 3 ++- docs/skills/asset-management.md | 2 +- docs/skills/cms-assets.md | 1 + skills/asset-management/SKILL.md | 19 ++++++++++++------- skills/cms-assets/SKILL.md | 6 ++++-- 6 files changed, 22 insertions(+), 12 deletions(-) diff --git a/docs/how-it-works/router.md b/docs/how-it-works/router.md index a30e566..04ea0b0 100644 --- a/docs/how-it-works/router.md +++ b/docs/how-it-works/router.md @@ -41,7 +41,8 @@ Each description's "Use when…" clause lists the requests that should load it. | Designing or refactoring content models | [Data Modeling Best Practices](../skills/cms-data-modeling-best-practices.md) | | Setting up or debugging Live Preview, Visual Editor (Visual Builder) or Timeline | [Live Preview & Visual Editor Support](../skills/cms-live-preview-visual-editor-support-assistant.md) | | Fetching entries, CDA queries, pagination, bulk ops | [Entries](../skills/cms-entries.md) | -| Uploading, transforming, delivering assets | [Assets](../skills/cms-assets.md) | +| Uploading, transforming, delivering assets in a stack | [Assets](../skills/cms-assets.md) | +| Assets DAM: spaces, workspaces, duplicate sets, saved views, visual markups | [Asset Management](../skills/asset-management.md) | | Classifying content, category hierarchies | [Taxonomy](../skills/cms-taxonomy.md) | | Workflow stages, approvals, publish rules | [Workflows & Publish Rules](../skills/cms-workflows.md) | | Environments, publishing, delivery/preview tokens, Sync API | [Environments & Publishing](../skills/cms-environments-publishing.md) | diff --git a/docs/overview/introduction.md b/docs/overview/introduction.md index 8656258..ac35d85 100644 --- a/docs/overview/introduction.md +++ b/docs/overview/introduction.md @@ -24,11 +24,12 @@ Agent skills close that gap. They give the assistant Contentstack-specific knowl ## What's in the bundle -The skills span six Contentstack product areas: +The skills span seven Contentstack product areas: | Product | Skills | | --- | --- | | **CMS** | Assets · Branches & Aliases · Data Modeling · Entries · Environments & Publishing · Localization · Releases · Roles & Permissions · Taxonomy · Tokens & Authentication · Variants & Personalization · Webhooks · Workflows | +| **Assets** | Asset Management | | **Developer Experience** | Delivery SDK · Contentstack Kickstart Next · Migrate JS→TS SDK · Live Preview & Visual Editor Support · Migration Companion | | **Studio** | Contentstack Studio | | **Launch** | Sync env vars from `.env.example` · Trigger & Monitor Deployments | diff --git a/docs/skills/asset-management.md b/docs/skills/asset-management.md index 4829cb8..55bb682 100644 --- a/docs/skills/asset-management.md +++ b/docs/skills/asset-management.md @@ -19,7 +19,7 @@ When you ask about the Assets DAM: spaces and workspaces, folders, asset types a - **Folders and roles**: folder creation and least-privilege guidance. - **Asset types and metadata**: system, general and user-defined metadata. User-defined field types are single line text, number, select and group. Filters on user-defined fields can be saved as saved views. - **Localization**: add a language in product settings, then add it per workspace under Space Settings > Workspaces > Manage Locales. -- **Search by user-defined field**: request shape, supported operators, and the `workspace` requirement. +- **Search**: the public Assets API search endpoint, required headers, and filtering by user-defined field. - **AI tags and alt text**: manual suggestions and auto-populate at upload, with their limits. - **Duplicate management**: exact-duplicate sets for images, how to resolve them, and what is not detected. - **Versions, trash and restore**: renaming and restoring versions, the 14-day trash window, and folder restore options. diff --git a/docs/skills/cms-assets.md b/docs/skills/cms-assets.md index 990099b..c7e558a 100644 --- a/docs/skills/cms-assets.md +++ b/docs/skills/cms-assets.md @@ -35,4 +35,5 @@ Read-only advisory. Never uploads, deletes, publishes, or modifies assets. Deliv ## Related +- For the standalone Assets DAM (spaces, workspaces, duplicate sets), see [Asset Management](asset-management.md). - [Environments & Publishing](cms-environments-publishing.md) · [Entries](cms-entries.md) · [Data Modeling Best Practices](cms-data-modeling-best-practices.md) diff --git a/skills/asset-management/SKILL.md b/skills/asset-management/SKILL.md index 2038e34..63d3a48 100644 --- a/skills/asset-management/SKILL.md +++ b/skills/asset-management/SKILL.md @@ -59,7 +59,7 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi ## Workflow Summary 1. Confirm the user means the Assets DAM, not the CMS asset library. -2. Identify the topic: structure, metadata, AI, duplicates, versions, trash, markups, editing, or CMS integration. +2. Identify the topic: structure, metadata, AI, duplicates, versions, trash, markups, or CMS integration. 3. Answer with documented behavior using the product's terminology. 4. Flag limits and irreversible actions. 5. Link to the relevant docs page for anything undocumented or likely to change. @@ -90,7 +90,7 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - Metadata comes in layers: **system metadata** (read-only: file name, UID, URLs, MIME type, size, created and modified details), **general metadata**, and **user-defined metadata** from custom fields. - Each **asset type** maps to one MIME type and one file extension. On upload, a matching type applies automatically and its fields appear. System types cover images, audio, video, documents and archives, and you can add custom types. -- User-defined fields are reusable across asset types. The supported field types are single line text, number, select and group. Do not suggest other types, such as multi line text, date, boolean or link. +- User-defined fields are reusable across asset types. The currently supported field types are single line text, number, select and group. The product docs have listed this set differently over time, so point the user to the Asset Modeling docs if they need a type that isn't on this list. - Mandatory fields must be filled before an upload or save can finish. Use them sparingly so uploads are not blocked on optional information. - Edit metadata for an individual asset in the configurable metadata panel. - **Filters and saved views:** User-defined fields can be used as filters when browsing assets, so well-modeled fields make the library searchable. A filter combination can be saved as a **saved view** and reused later instead of rebuilding the filters each time. Advise modeling fields with filtering in mind, for example a select field for campaign or usage rights. @@ -103,12 +103,17 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi 2. Add it to each workspace that needs it: **Space Settings > Workspaces >** pick the workspace **> Manage Locales**. - Locales are enabled per workspace, so a language added in product settings does not appear in a workspace until it is added there. -### Filtering assets by user-defined fields +### Searching assets and filtering by user-defined fields -- To filter by a user-defined field in the Assets search API, send the condition in `query` and use the field's full path: `user_defined_fields..`. Wrap conditions in `$and` or `$or` to combine them. -- Every value must be an operator object, not a plain value. Supported operators are `$eq`, `$ne`, `$in`, `$nin`, `$contains`, `$lt`, `$lte`, `$gt`, `$gte`, `$exists`, `$range` and `$not`. `$regex` is not supported. -- Each entry in `spaces` needs both a `space_uid` and a `workspace` string, for example `"main"`. -- `search_field` only accepts `all`, `title`, `name`, `url` or `category`. It can't target user-defined fields, so use `query` for those. +Use the Assets API search endpoint. Full reference: https://www.contentstack.com/docs/developers/apis/assets-api/search + +- **Endpoint:** `POST https://am-api.contentstack.com/api/{object_type}/search`. `object_type` is required. Folders are not searchable here. +- **Headers:** send either `authorization: Bearer ` or `authtoken` (your Contentstack authtoken). A management token is not accepted. `x-cs-api-version` is required (default `4`). With `authtoken`, `organization_uid` is also required. Read tokens from environment variables. +- **Text search:** `search_text`, `search_field` and `search_terms_operator` (`and` or `or`). `search_field` accepts only `all`, `title`, `name`, `url` or `category`, so it cannot target user-defined fields. +- **Structured filters:** put conditions in `query`, combined with `$and` and `$or`. Filter a user-defined field by its full path: `user_defined_fields..`. +- **Operator objects:** write each condition as an operator object, for example `{ "$eq": "value" }`, not a bare value. Operators in use include `$eq`, `$ne`, `$in`, `$nin`, `$contains`, `$lt`, `$lte`, `$gt`, `$gte`, `$exists`, `$range` and `$not`. `$regex` is not supported. The public page documents `$and` and `$or` explicitly and does not list the comparison operators, so tell the user to test their filter. +- **Scope and paging:** `spaces` limits the search. Give each entry a `space_uid` and a `workspace` string such as `"main"`. Use `limit` and `skip` for paging, and `fields` to trim the response. +- Deleted items are excluded unless `include_deleted_items` or `filter_only_deleted_items` is set. Example request body: diff --git a/skills/cms-assets/SKILL.md b/skills/cms-assets/SKILL.md index 8a9da34..3ef34de 100644 --- a/skills/cms-assets/SKILL.md +++ b/skills/cms-assets/SKILL.md @@ -1,6 +1,6 @@ --- name: cms-assets -description: "Advise developers on organizing, delivering, and transforming assets in Contentstack. Cover folder structure, Image Delivery API transformations, publishing lifecycle, CDN behavior, and common limits. Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack." +description: "Advise developers on organizing, delivering, and transforming assets in Contentstack. Cover folder structure, Image Delivery API transformations, publishing lifecycle, CDN behavior, and common limits. Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in a stack's asset library. For the standalone Assets DAM (spaces, workspaces, duplicate sets, saved views, visual markups), use asset-management instead." allowed-tools: Read Grep Glob --- @@ -12,7 +12,9 @@ Advise developers on organizing, delivering, and transforming assets in Contents ## When to Use -Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. +Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in a stack's asset library. + +For the standalone Assets DAM product (spaces, workspaces, duplicate sets, saved views, visual markups), use the `asset-management` skill instead. ## User Problem From 0cbde4ac5c04c03974fa1f1b93b02c2b461ba97e Mon Sep 17 00:00:00 2001 From: Mun-GitHub Date: Tue, 20 Oct 2026 14:14:00 +0530 Subject: [PATCH 6/8] Route user-defined field read/update to the Assets (DAM) API The stack asset library does not support user-defined fields. Say so in cms-assets and its docs page, and point asset-management at the Assets API. Co-Authored-By: Claude Sonnet 5.5 --- docs/skills/cms-assets.md | 2 +- skills/asset-management/SKILL.md | 1 + skills/cms-assets/SKILL.md | 4 +++- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/skills/cms-assets.md b/docs/skills/cms-assets.md index c7e558a..5829875 100644 --- a/docs/skills/cms-assets.md +++ b/docs/skills/cms-assets.md @@ -35,5 +35,5 @@ Read-only advisory. Never uploads, deletes, publishes, or modifies assets. Deliv ## Related -- For the standalone Assets DAM (spaces, workspaces, duplicate sets), see [Asset Management](asset-management.md). +- For the standalone Assets DAM (spaces, workspaces, duplicate sets), see [Asset Management](asset-management.md). Reading or updating user-defined fields isn't supported by the stack asset library; use the Assets (DAM) API described there. - [Environments & Publishing](cms-environments-publishing.md) · [Entries](cms-entries.md) · [Data Modeling Best Practices](cms-data-modeling-best-practices.md) diff --git a/skills/asset-management/SKILL.md b/skills/asset-management/SKILL.md index 63d3a48..25b04d3 100644 --- a/skills/asset-management/SKILL.md +++ b/skills/asset-management/SKILL.md @@ -93,6 +93,7 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi - User-defined fields are reusable across asset types. The currently supported field types are single line text, number, select and group. The product docs have listed this set differently over time, so point the user to the Asset Modeling docs if they need a type that isn't on this list. - Mandatory fields must be filled before an upload or save can finish. Use them sparingly so uploads are not blocked on optional information. - Edit metadata for an individual asset in the configurable metadata panel. +- User-defined fields exist only in the Assets (DAM) product. The CMS stack asset library and its Management API don't read or update them, so direct any request to read or write custom metadata from code to the Assets (DAM) API. See the Assets API reference at https://www.contentstack.com/docs/developers/apis/assets-api for the current endpoints. - **Filters and saved views:** User-defined fields can be used as filters when browsing assets, so well-modeled fields make the library searchable. A filter combination can be saved as a **saved view** and reused later instead of rebuilding the filters each time. Advise modeling fields with filtering in mind, for example a select field for campaign or usage rights. ### Localization diff --git a/skills/cms-assets/SKILL.md b/skills/cms-assets/SKILL.md index 3ef34de..37b1985 100644 --- a/skills/cms-assets/SKILL.md +++ b/skills/cms-assets/SKILL.md @@ -1,6 +1,6 @@ --- name: cms-assets -description: "Advise developers on organizing, delivering, and transforming assets in Contentstack. Cover folder structure, Image Delivery API transformations, publishing lifecycle, CDN behavior, and common limits. Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in a stack's asset library. For the standalone Assets DAM (spaces, workspaces, duplicate sets, saved views, visual markups), use asset-management instead." +description: "Advise developers on organizing, delivering, and transforming assets in Contentstack. Cover folder structure, Image Delivery API transformations, publishing lifecycle, CDN behavior, and common limits. Use when developers ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in a stack's asset library. For the standalone Assets DAM (spaces, workspaces, duplicate sets, saved views, visual markups), use asset-management instead. Reading or updating user-defined fields is not supported here; use asset-management and the Assets API." allowed-tools: Read Grep Glob --- @@ -16,6 +16,8 @@ Use when developers ask about uploading, organizing, delivering, transforming, p For the standalone Assets DAM product (spaces, workspaces, duplicate sets, saved views, visual markups), use the `asset-management` skill instead. +This skill does not cover reading or updating user-defined fields (custom metadata). The stack asset library doesn't support them. Route those requests to the `asset-management` skill, which points to the Assets (DAM) API. + ## User Problem Developers need to organize assets effectively, serve optimized images, and understand how asset publishing and CDN delivery work. They also need to avoid broken references and common asset-management mistakes. From 6d6f041a8bbedbbc346a08443f94f1c3443f1195 Mon Sep 17 00:00:00 2001 From: Mun-GitHub Date: Tue, 20 Oct 2026 18:06:55 +0530 Subject: [PATCH 7/8] Address second review: search spaces shape, regional hosts, auth env vars; bump to 0.3.0 - spaces is a plain array of UIDs; list regional hosts and flag the .io/.com mismatch - Use authtoken/OAuth env vars, not a management token - Match 'currently supported' field-type wording in the docs page - Fix docs/README.md table padding - Bump version to 0.3.0 in all manifests and add a CHANGELOG entry Co-Authored-By: Claude Sonnet 5.5 --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- CHANGELOG.md | 10 ++++++++++ docs/README.md | 2 +- docs/skills/asset-management.md | 2 +- gemini-extension.json | 2 +- plugin.json | 2 +- skills/asset-management/SKILL.md | 9 +++++---- 9 files changed, 22 insertions(+), 11 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4dc816b..a86b657 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ "name": "contentstack-skills", "source": "./", "description": "Contentstack agent skills for CMS modeling, Delivery SDK, Live Preview, Studio, Brand Kit, Developer Hub apps, Launch, and migrations.", - "version": "0.2.0", + "version": "0.3.0", "category": "development", "tags": ["contentstack", "cms", "headless-cms", "studio"] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 7c519d1..24779cd 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "contentstack-skills", - "version": "0.2.0", + "version": "0.3.0", "description": "Contentstack agent skills for CMS modeling, Delivery SDK, Live Preview, Studio, Brand Kit, Developer Hub apps, Launch, and migrations.", "author": { "name": "Contentstack", "url": "https://www.contentstack.com" }, "homepage": "https://developers.contentstack.com", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index f80d783..e51e220 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "contentstack-skills", - "version": "0.2.0", + "version": "0.3.0", "description": "Contentstack agent skills for CMS modeling, Delivery SDK, Live Preview, Studio, Brand Kit, Developer Hub apps, Launch, and migrations.", "author": { "name": "Contentstack", "url": "https://www.contentstack.com" }, "skills": "./skills/" diff --git a/CHANGELOG.md b/CHANGELOG.md index e6ce1a5..142738a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,16 @@ All notable changes to the Contentstack agent skills bundle. Versions match the `version` field in every plugin manifest that declares one. +## 0.3.0 + +### New skills + +- `asset-management`: advisory guidance for the standalone Assets (DAM) product: spaces and workspaces, folders, asset types and user-defined fields, localization, saved views, searching the Assets API, AI tags and alt text, duplicate management, versions, trash and restore, visual markups and CMS integration. + +### Changed skills + +- **`cms-assets` routing:** scoped to the stack asset library. Assets DAM questions, and any request to read or update user-defined fields, now route to `asset-management`, since the stack asset library doesn't support user-defined fields. + ## 0.2.0 ### Install anywhere, from one source diff --git a/docs/README.md b/docs/README.md index 0503fa8..3a85c43 100644 --- a/docs/README.md +++ b/docs/README.md @@ -51,7 +51,7 @@ Every skill is written once in the open [Agent Skills](https://agentskills.io) f | | | | ------------------------ | -------------------------------------------------------------------------------------------------------------- | | **Skills included** | 24 (see the [skill reference](skills/index.md)) | -| **Products covered** | CMS, Assets, Developer Experience, Studio, Launch, Brand Kit, Developer Hub | +| **Products covered** | CMS, Assets, Developer Experience, Studio, Launch, Brand Kit, Developer Hub | | **Supported tools** | Claude Code, claude.ai / Cowork, Cursor, Codex, GitHub Copilot, Gemini CLI, `skills` CLI | | **Source of truth** | `skills//SKILL.md` | | **Repository** | [github.com/contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills) | diff --git a/docs/skills/asset-management.md b/docs/skills/asset-management.md index 55bb682..c5b91f1 100644 --- a/docs/skills/asset-management.md +++ b/docs/skills/asset-management.md @@ -17,7 +17,7 @@ When you ask about the Assets DAM: spaces and workspaces, folders, asset types a - **Spaces and workspaces**: a space is the top-level container, and workspaces are isolated environments inside it, created from the main workspace or a parent workspace. - **Folders and roles**: folder creation and least-privilege guidance. -- **Asset types and metadata**: system, general and user-defined metadata. User-defined field types are single line text, number, select and group. Filters on user-defined fields can be saved as saved views. +- **Asset types and metadata**: system, general and user-defined metadata. The currently supported user-defined field types are single line text, number, select and group. Filters on user-defined fields can be saved as saved views. - **Localization**: add a language in product settings, then add it per workspace under Space Settings > Workspaces > Manage Locales. - **Search**: the public Assets API search endpoint, required headers, and filtering by user-defined field. - **AI tags and alt text**: manual suggestions and auto-populate at upload, with their limits. diff --git a/gemini-extension.json b/gemini-extension.json index 9538e1b..57ac9e7 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,5 +1,5 @@ { "name": "contentstack-skills", - "version": "0.2.0", + "version": "0.3.0", "description": "Contentstack agent skills for CMS modeling, Delivery SDK, Live Preview, Studio, Brand Kit, Developer Hub apps, Launch, and migrations." } diff --git a/plugin.json b/plugin.json index 0c8c924..03de702 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "contentstack-skills", - "version": "0.2.0", + "version": "0.3.0", "description": "Contentstack agent skills for CMS modeling, Delivery SDK, Live Preview, Studio, Brand Kit, Developer Hub apps, Launch, and migrations.", "author": { "name": "Contentstack", "url": "https://www.contentstack.com" }, "homepage": "https://developers.contentstack.com", diff --git a/skills/asset-management/SKILL.md b/skills/asset-management/SKILL.md index 25b04d3..211b63b 100644 --- a/skills/asset-management/SKILL.md +++ b/skills/asset-management/SKILL.md @@ -108,12 +108,13 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi Use the Assets API search endpoint. Full reference: https://www.contentstack.com/docs/developers/apis/assets-api/search -- **Endpoint:** `POST https://am-api.contentstack.com/api/{object_type}/search`. `object_type` is required. Folders are not searchable here. +- **Endpoint:** `POST /api/{object_type}/search`. `object_type` is required. Folders are not searchable here. +- **Host by region:** use the base URL for your region from the [Assets API overview](https://www.contentstack.com/docs/developers/apis/assets-api): AWS NA, AWS EU (`eu-am-api.contentstack.com`), Azure NA (`azure-na-am-api.contentstack.com`) or GCP NA (`gcp-na-am-api.contentstack.com`). The docs show the AWS NA host as `am-api.contentstack.io` on the overview and `am-api.contentstack.com` on the search page, so confirm it against the overview. - **Headers:** send either `authorization: Bearer ` or `authtoken` (your Contentstack authtoken). A management token is not accepted. `x-cs-api-version` is required (default `4`). With `authtoken`, `organization_uid` is also required. Read tokens from environment variables. - **Text search:** `search_text`, `search_field` and `search_terms_operator` (`and` or `or`). `search_field` accepts only `all`, `title`, `name`, `url` or `category`, so it cannot target user-defined fields. - **Structured filters:** put conditions in `query`, combined with `$and` and `$or`. Filter a user-defined field by its full path: `user_defined_fields..`. - **Operator objects:** write each condition as an operator object, for example `{ "$eq": "value" }`, not a bare value. Operators in use include `$eq`, `$ne`, `$in`, `$nin`, `$contains`, `$lt`, `$lte`, `$gt`, `$gte`, `$exists`, `$range` and `$not`. `$regex` is not supported. The public page documents `$and` and `$or` explicitly and does not list the comparison operators, so tell the user to test their filter. -- **Scope and paging:** `spaces` limits the search. Give each entry a `space_uid` and a `workspace` string such as `"main"`. Use `limit` and `skip` for paging, and `fields` to trim the response. +- **Scope and paging:** `spaces` limits the search and is a plain array of space UIDs, as in the docs example. Use `limit` and `skip` for paging, and `fields` to trim the response. - Deleted items are excluded unless `include_deleted_items` or `filter_only_deleted_items` is set. Example request body: @@ -126,7 +127,7 @@ Example request body: ] }, "limit": 50, - "spaces": [{ "space_uid": "", "workspace": "main" }] + "spaces": [""] } ``` @@ -224,7 +225,7 @@ Never reveal management tokens, API keys or other secrets. Reference environment ### Environment Variables -Use environment variables for any credentialed example, such as `CONTENTSTACK_API_KEY` and `CONTENTSTACK_MANAGEMENT_TOKEN`. Never hardcode credentials in client-side code. +Use environment variables for any credentialed example, such as `CONTENTSTACK_AUTHTOKEN` or `CONTENTSTACK_OAUTH_ACCESS_TOKEN` and `CONTENTSTACK_ORGANIZATION_UID`. The Assets API does not accept management tokens. Never hardcode credentials in client-side code. ## Product Context From 99844e605f35e753525abe26f66f020854d58835 Mon Sep 17 00:00:00 2001 From: Tim Benniks Date: Fri, 23 Oct 2026 12:08:33 +0200 Subject: [PATCH 8/8] asset-management: keep search guidance to the documented API - List the AWS NA host (am-api.contentstack.com), now consistent in the docs - Drop the undocumented operator list and $regex claim; use the documented field-value form - Flag user-defined field paths as something to test against the space - Clarify that the organization UID pairs with the authtoken Co-Authored-By: Claude Opus 5.5 --- skills/asset-management/SKILL.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/skills/asset-management/SKILL.md b/skills/asset-management/SKILL.md index 211b63b..4ce64da 100644 --- a/skills/asset-management/SKILL.md +++ b/skills/asset-management/SKILL.md @@ -109,11 +109,10 @@ Teams adopting Contentstack Assets need to structure spaces and workspaces sensi Use the Assets API search endpoint. Full reference: https://www.contentstack.com/docs/developers/apis/assets-api/search - **Endpoint:** `POST /api/{object_type}/search`. `object_type` is required. Folders are not searchable here. -- **Host by region:** use the base URL for your region from the [Assets API overview](https://www.contentstack.com/docs/developers/apis/assets-api): AWS NA, AWS EU (`eu-am-api.contentstack.com`), Azure NA (`azure-na-am-api.contentstack.com`) or GCP NA (`gcp-na-am-api.contentstack.com`). The docs show the AWS NA host as `am-api.contentstack.io` on the overview and `am-api.contentstack.com` on the search page, so confirm it against the overview. +- **Host by region:** use the base URL for your region from the [Assets API overview](https://www.contentstack.com/docs/developers/apis/assets-api): AWS NA (`am-api.contentstack.com`), AWS EU (`eu-am-api.contentstack.com`), Azure NA (`azure-na-am-api.contentstack.com`) or GCP NA (`gcp-na-am-api.contentstack.com`). - **Headers:** send either `authorization: Bearer ` or `authtoken` (your Contentstack authtoken). A management token is not accepted. `x-cs-api-version` is required (default `4`). With `authtoken`, `organization_uid` is also required. Read tokens from environment variables. - **Text search:** `search_text`, `search_field` and `search_terms_operator` (`and` or `or`). `search_field` accepts only `all`, `title`, `name`, `url` or `category`, so it cannot target user-defined fields. -- **Structured filters:** put conditions in `query`, combined with `$and` and `$or`. Filter a user-defined field by its full path: `user_defined_fields..`. -- **Operator objects:** write each condition as an operator object, for example `{ "$eq": "value" }`, not a bare value. Operators in use include `$eq`, `$ne`, `$in`, `$nin`, `$contains`, `$lt`, `$lte`, `$gt`, `$gte`, `$exists`, `$range` and `$not`. `$regex` is not supported. The public page documents `$and` and `$or` explicitly and does not list the comparison operators, so tell the user to test their filter. +- **Structured filters:** put conditions in `query`, combined with nested `$and` and `$or` clauses. The docs match a field to a value, for example `{ "category": "image" }`, and don't document other operators. To filter a user-defined field, reference it by its full path, `user_defined_fields..`, and test the filter against your space, since the public page doesn't cover user-defined fields. - **Scope and paging:** `spaces` limits the search and is a plain array of space UIDs, as in the docs example. Use `limit` and `skip` for paging, and `fields` to trim the response. - Deleted items are excluded unless `include_deleted_items` or `filter_only_deleted_items` is set. @@ -123,7 +122,7 @@ Example request body: { "query": { "$and": [ - { "user_defined_fields.asset_rights.license_type": { "$eq": "Creative Commons" } } + { "user_defined_fields.asset_rights.license_type": "Creative Commons" } ] }, "limit": 50, @@ -225,7 +224,7 @@ Never reveal management tokens, API keys or other secrets. Reference environment ### Environment Variables -Use environment variables for any credentialed example, such as `CONTENTSTACK_AUTHTOKEN` or `CONTENTSTACK_OAUTH_ACCESS_TOKEN` and `CONTENTSTACK_ORGANIZATION_UID`. The Assets API does not accept management tokens. Never hardcode credentials in client-side code. +Use environment variables for any credentialed example, such as `CONTENTSTACK_OAUTH_ACCESS_TOKEN`, or `CONTENTSTACK_AUTHTOKEN` together with `CONTENTSTACK_ORGANIZATION_UID`. The Assets API does not accept management tokens. Never hardcode credentials in client-side code. ## Product Context