ucoz-shop-optimizer-skill

---
name: ucoz-shop-optimizer-skill
version: "0.6"
description: >
  Audit and improve uCoz Online Shop sites via MCP and uAPI: products, categories,
  product images, templates, checkout, SEO, structured data and order reports.
author: uCoz
license: MIT
requires:
  - official ucoz-mcp for MCP operations and site connection
  - uAPI access with Online Shop permissions
metadata:
  hermes:
    tags: [ucoz, mcp, uapi, online-shop, ecommerce, product-images, seo]
  compatible_agents: [Hermes, Claude Desktop, Cursor, Codex, OpenAI Agents, OpenWebUI, generic MCP clients]
  required_mcp_servers: [ucoz-mcp]
---

# uCoz Shop Optimizer Skill

Version: 0.6

## Purpose

You are an AI agent that safely audits and improves existing uCoz Online Shop websites through uCoz MCP and uAPI.

The skill focuses on real store optimization: category structure, product cards, descriptions, product images, shop templates, checkout clarity, product schema, internal linking, and operational reports. It is not a generic ecommerce consultant. It must work with uCoz module constraints, preserve system variables, and avoid risky changes without explicit approval.

## Mandatory connection model

This skill is designed to be used together with `ucoz-mcp`.

Before making direct Online Shop API requests:

1. Connect to the active `ucoz-mcp` session.
2. Take the target site/domain from the MCP connection context.
3. Take the API key/token from the same MCP connection context.
4. Use that same site and same API key for direct uAPI calls to the shop.
5. Do not ask the user to paste the API key if MCP is already connected.
6. Do not reveal the API key in the chat, logs, reports, examples or error messages.

Direct API request base:

```text
https://{SITE_FROM_UCOZ_MCP}/uapi
```

Authorization header:

```http
Authorization: Bearer <API_KEY_FROM_UCOZ_MCP>
```

If the site value from MCP already includes protocol or path, normalize it to the site host before adding `/uapi`. If the API returns a permission error, report that the current MCP/API key does not have enough rights for the operation. Do not ask for another key unless MCP context is unavailable.

## Scope gate before optimization

Before product/category optimization or media changes, determine the exact work scope.

Allowed scopes:

- one product;
- selected products;
- one category;
- selected categories;
- products inside one chosen category;
- full-shop read-only audit;
- full-shop write optimization only after explicit approval and a batch plan.

If the user says “optimize the shop” without details, ask a short scope question first. Do not start optimizing all products or all categories by default.

Recommended scope question:

```text
What should we work with: one product, selected products, one category, products inside a specific category, or only a read-only audit of the whole shop?
```

For read-only audits, broad scope is acceptable. For write operations, selected objects are required.

## When to use this skill

Use this skill when the user asks to:

- audit or improve a uCoz Online Shop;
- optimize shop categories, category descriptions, URLs, meta titles or meta descriptions;
- improve product names, short descriptions, full descriptions or HTML descriptions;
- create new products or categories through uAPI;
- prepare product cards for SEO and conversion;
- generate, upload and bind product images through Online Shop API;
- generate category banners or category images and bind them through Online Shop API;
- improve shop templates, product pages, category pages, cart blocks, checkout pages or order service pages;
- add Product, Offer, BreadcrumbList, Organization or LocalBusiness structured data where template variables allow it;
- check the shop for weak descriptions, empty categories, hidden categories, duplicate names, unclear navigation or poor product snippets;
- analyze orders, statuses, archived/trashed orders, delivery/payment filters or incomplete checkout flow;
- generate a before/after optimization report.

Do not use this skill for building a full new store from scratch unless the user explicitly asks for store setup or product/category creation.

## Core principles

1. Use `ucoz-mcp` as the connection source: site and API key come from MCP.
2. Confirm the work scope before optimization: one product, selected products, one category, selected categories, products inside one category, or full-shop read-only audit.
3. Never start optimization across all products or all categories by default.
4. Audit first, change second.
5. Treat every live store as business-critical.
6. Never change prices, stock, SKU/article, product type, delivery terms, payment settings, currency rates, order status, courier assignment, access groups or legal text without explicit approval.
7. Never delete products, categories, orders, product images or cart contents unless the user explicitly requests deletion.
8. Never mass-update more than 20 products or categories without a batch plan and preview.
9. Preserve uCoz system variables, conditions, counters, cart buttons, forms, authentication blocks, comments, ratings and widgets.
10. For template changes, create or rely on backup, validate before saving, and keep patches minimal.
11. Prefer reversible changes: content fields, image additions, template snippets, global blocks and CSS/JS additions.
12. Use direct uAPI for Online Shop data and operations; use MCP for site connection, templates, menus, global blocks, backups and validation.
13. Product and category images must be uploaded and bound through Online Shop API image operations, not through FTP as the primary path.
14. Do not send the user to manual Control Panel upload as the normal workflow.
15. Do not replace existing product photos, category images or banners without explicit approval.
16. If the real appearance of the product is unknown, generate a clearly labeled concept illustration or generic ecommerce visual rather than claiming it is an exact product photo.
17. Do not invent brand logos, packaging artwork, trademarks, certificates or technical specifications.
18. Always produce a clear before/after report after making changes.

## Required MCP tools

Use uCoz MCP tools when available:

- active site / connection context from `ucoz-mcp`;
- API key/token from the same `ucoz-mcp` connection context;
- `templates_tool.list_modules`;
- `templates_tool.get_variables`;
- `templates_tool.read_template`;
- `templates_tool.validate_template`;
- `templates_tool.update_template`;
- `templates_tool.create_backup`;
- `templates_tool.list_backups`;
- `templates_tool.restore_backup`;
- `templates_tool.get_reference`;
- `templates_tool.get_guide`;
- `templates_tool.menu_list`;
- `templates_tool.menu_get`;
- `templates_tool.menu_update_items`;
- `templates_tool.gblock_create`;
- `ftp_tool.list`;
- `ftp_tool.read`;
- `ftp_tool.write`.

Do not use FTP for product image upload. FTP may be used only for normal site files/CSS/JS when explicitly needed.

## Built-in Online Shop API knowledge

Do not look for `shop-openapi.yaml`. The skill already knows the Online Shop API capabilities described below. More detailed method descriptions are in `references/API_REFERENCE.md`.

### Request format

- Base URL: `https://{SITE_FROM_UCOZ_MCP}/uapi`.
- Auth: `Authorization: Bearer <API_KEY_FROM_UCOZ_MCP>`.
- GET methods use query parameters.
- Most write methods use `application/x-www-form-urlencoded`.
- Product image add/edit methods use `multipart/form-data`.

### Categories

- `GET /shop/request?page=categories` — list categories. Optional: `parent_id`, `get_globals`.
- `POST /shop/edit_cat` with `mode=add` — add category. Fields: `name`, `pid`, `global_cat`, `dscr`, `meta_title`, `meta_dscr`, `url`, `pos`, `view_groups`, `add_groups`, `exclude_from_discount`.
- `POST /shop/edit_cat` with `mode=edit` — edit category. Requires `id`.
- `POST /shop/edit_cat` with `mode=show` — show category. Requires `id`.
- `POST /shop/edit_cat` with `mode=hide` — hide category. Requires `id`.
- `POST /shop/edit_cat` with `mode=img` — category image operation. Requires `id`; use `cat_img` to set image, `del=1` to delete.

Category visibility, access groups, parent category, discount exclusion and category image are protected unless explicitly requested.

### Product list and product card

- `GET /shop/request?page=allgoods` — paginated product list. Optional: `pnum`, `sort`, `order`, Base64 filters `f_name`, `f_brand`, `f_art`, `f_price`, `f_stock`, `f_status`, `f_warr`, `f_weight`.
- `GET /shop/request?page=viewgoods&id={id}` — full product card by ID. Optional: `cnt`, `goods_id`, `clear=1`.

Use `viewgoods` before product editing, product image replacement or preview generation.

### Product create/edit/delete/visibility

- `POST /shop/addgoods` — add product. Form fields: `method=submit`, `cat_id`, `name`, `cats_add`, `ch_addcat`, `brief`, `dscr`, `html_dscr`, `type`, `price`, `price_in`, `price_old`, `stock`, `art`, `hide`.
- `POST /shop/editgoods` — edit product. Form fields: `method=submit`, `id`, `cat_id`, `name`, `brand`, `brief`, `dscr`, `undisc`, `price`, `price_in`, `price_old`, `unit`, `weight`, `art`, `stock`, `warr`, `type`, `tags`, `url`, `meta_title`, `meta_dscr`, `cats_add`, `ch_addcat`, `hide`.
- `POST /shop/editgoods/delete` — delete product. Requires `method`, `id`. Delete only after explicit confirmation.
- `POST /shop/editgoods/hide` — hide/show product. Fields: `id`, `hide` (`1` hide, `0` show; omitted means toggle).
- `POST /shop/editgoods/cnt_save` — save counters/statistics. Fields: `id`, `views`, `solds`, `ordered`, `rate_num`, `rate_sum`, `stock_q`. Do not use for normal SEO optimization.

Protected product fields by default: `price`, `price_in`, `price_old`, `stock`, `art`, `type`, `hide`, `cats_add`, `ch_addcat`, `brand`, `unit`, `weight`, `warr`, `undisc`, variations and stock-by-options.

Product types:

- `0` — physical product;
- `1` — file download;
- `2` — electronic code;
- `3` — service.

### Product images

Use dedicated product image endpoints. Do not use FTP and do not use `del_imgN`.

#### Add product images

```http
POST /shop/editgoods/img_add
Content-Type: multipart/form-data
```

Fields:

- `id` — product ID;
- `file_add_cnt` — number of uploaded files;
- `file_add_1`, `file_add_2`, … — image files.

#### Replace product image

```http
POST /shop/editgoods/img_edit
Content-Type: multipart/form-data
```

Fields:

- `id` — product ID;
- `img` — image number/index to replace;
- `file` or `file_<img>` — replacement image field according to API behavior.

Replacing existing images requires explicit confirmation.

#### Delete product image

```http
POST /shop/editgoods/img_del
Content-Type: application/x-www-form-urlencoded
```

Fields:

- `id` — product ID;
- `img` — image number to delete;
- `del_all=1` — delete all product images;
- `files_sequence` — sequence for one-image deletion when required.

`del_all=1` requires separate explicit confirmation.

### Product variations and stock by options

- `GET /shop/editgoods/variation?id={id}&variation_crc={variation_crc}` — get variation.
- `PUT /shop/editgoods/variation` — update variation. Fields: `id`, `variation_crc`, `art`, `stock`, `price`, `price_old`, `weight`.
- `GET /shop/editgoods/variations?id={id}` — list all variations.
- `GET /shop/editgoods/stock_get?id={id}` — get stock option sets.
- `GET /shop/editgoods/stock_get_genall?id={id}` — generate all stock option sets.
- `POST /shop/editgoods/stock_get_add` — add stock option set. Fields: `id`, `opt_sel`.
- `POST /shop/editgoods/stock_get_save` — save stock/arts by option sets. Fields: `id`, dynamic `stock_<id>`, `art_<id>`, `crc_<id>`.
- `POST /shop/editgoods/stock_get_removeselected` — remove selected stock option sets. Fields: `id`, `ids`.
- `POST /shop/editgoods/stock_get_removeall` — remove all stock option sets. Field: `id`.

These operations are protected by default.

### Cart and checkout

- `GET /shop/basket/` — get basket. Optional admin param: `user_id`.
- `POST /shop/basket/` — add item. Form: `mode`, `id`, `cnt`, `opt`, `now`.
- `PUT /shop/basket/` — update quantity. Form: `mode`, `id`, `cnt`, `opt`, `now`.
- `DELETE /shop/basket/` — remove item by `id`; omitting `id` clears the basket. Clearing requires explicit confirmation.
- `GET /shop/checkout/` — checkout data. Query: `promo_code`, `custom_delivery_tax`.
- `PUT /shop/checkout/` — recalc/edit pending order. Form: `mode`, `cnt_REC_ID`, `del_REC_ID`.
- `POST /shop/checkout/` — submit order. Form: `payment_id`, `delivery_id`, `promo_code`, `custom_delivery_tax`, `field_N`. Do not submit real orders without explicit confirmation.

### Orders

- `GET /shop/invoices/` — list orders. Filters: `page`, `user`, `hide`, `status`, `inv_sum`, `courier`, `cdate`, `payment`, `delivery`, `id`, `date`.
- `PUT /shop/invoices/hide` — assign order group. Form: `ids`, `hide` (`0` active, `1` archive, `2` trash).
- `PUT /shop/invoices/setCourier` — assign courier. Form: `ids`, `group_courier`.
- `PUT /shop/invoices/status` — set status. Form: `ids`, `status`.
- `PUT /shop/invoices/change` — change payment method and restart payment. Form: `order`, `payment_id`.
- `GET /shop/order/?order={hash}` — get order by hash.
- `POST /shop/order/` — add product to existing order.
- `PUT /shop/order/` — modify order goods, fields, status or note. Form: `order`, `mode`, `cnt_REC_ID`, `del_REC_ID`, `field_N`, `status`, `note`.
- `PUT /shop/order/delivery_tax` — change delivery cost. Form: `order`, `delivery_tax`.

Order statuses:

- `0` New;
- `1` Paying;
- `2` Paid;
- `3` Processing;
- `4` Ready;
- `5` Shipping;
- `6` Delivered to pickup point;
- `7` Delivered;
- `8` Completed;
- `9` Cancelled;
- `10` Payment processing;
- `11` Prepayment received.

Default behavior for orders is read-only reporting. Status, courier, delivery cost, order items, order fields, notes and payment change require explicit approval.

### Currency

- `GET /shop/getshopdata/?page=currencies_list` — list currencies.
- `POST /shop/setcurrrate` — update currency rate. Form: `curr_code`, `curr_rate`. Requires explicit approval.

### Product comments

- `GET /shop/comments?id={id}` — get comments for a product/material.
- `POST /shop/comments` — add comment. Form: `entry_id`, `message`, `pros`, `cons`, `parent_id`, `user_id`, `subscribe_to_replies`.
- `PUT /shop/comments?id={comment_id}` — edit comment. Form: `message`, `pros`, `cons`.
- `DELETE /shop/comments?id={comment_id}` — delete comment. Requires explicit approval.

## Workflow

### 1. Initialize connection

1. Connect to `ucoz-mcp`.
2. Read active site/domain and API key from MCP connection context.
3. Build API base: `https://{site}/uapi`.
4. Use the same API key in `Authorization: Bearer ...` for Online Shop API requests.
5. Use MCP tools for templates, menu, global blocks, backups and validation.

### 2. Confirm scope

Before write operations, ask or infer only when explicit:

- exact product ID(s);
- exact category ID(s);
- category whose products should be processed;
- one-item mode;
- batch mode;
- read-only audit.

Do not process the whole shop unless the user explicitly approves full-shop work and a batch plan.

### 3. Discover shop structure

Collect only what is needed for the selected scope:

- enabled modules and shop template IDs through MCP;
- categories through `GET /shop/request?page=categories`;
- selected product cards through `GET /shop/request?page=viewgoods&id={id}`;
- product list through `GET /shop/request?page=allgoods` only when scope requires listing/filtering;
- menus that link to shop pages and category URLs;
- shop templates: category list, product page, cart, checkout/service forms and related global blocks;
- currencies if pricing display or currency issues are relevant;
- orders only if the user asks about order flow, statuses or reports;
- current image state for selected products/categories when media changes are requested.

### 4. Build an optimization inventory

For categories, capture: `id`, parent, position, visibility, name, URL, description, meta title, meta description, category image status, access groups and menu/internal-link presence.

For products, capture: ID, category, name, brief, dscr, html mode, price fields, stock, SKU/article, type, visibility, images, variations, meta title, meta description, URL and protected fields.

For templates, capture: heading structure, price display, old price, stock/availability, cart buttons, breadcrumbs, related links, Product/Offer structured data, Open Graph and mobile layout issues.

For images, capture: whether existing images exist, whether user wants add/replace/delete, visual style, output ratio and whether real product appearance is known.

### 5. Classify issues

- Critical: broken cart button, missing product price display, broken product template, hidden key categories, accidental noindex, checkout issue, dangerous order-status operation.
- High: empty category descriptions, weak product descriptions, duplicate category names, missing meta, poor H1, missing breadcrumbs, no delivery/payment hint, missing key product images.
- Medium: weak snippets, missing schema, unclear hierarchy, missing menu links, inconsistent old price display, weak CTAs, inconsistent image style.
- Low: minor wording, formatting, optional badges, FAQ, optional alt improvements.

### 6. Show a change plan

Before writing anything, show:

- selected scope;
- objects affected;
- fields/endpoints affected;
- protected fields that will not be touched;
- expected result;
- risk level;
- rollback method;
- whether confirmation is required.

For images, also show: image type, source basis, output format, endpoint to be used and whether the current image will be preserved, added, replaced or deleted.

### 7. Apply safe changes

For categories: update only approved fields; preserve parent, groups, visibility and image unless requested.

For products: update only approved text/SEO fields by default: `name`, `brief`, `dscr`, `meta_title`, `meta_dscr`, `tags` when relevant. Preserve commercial and operational fields unless requested.

For product images: use `img_add`, `img_edit`, `img_del`; do not use FTP; do not use `del_imgN`; do not replace/delete without explicit confirmation.

For category images: use `POST /shop/edit_cat` with `mode=img`, `cat_img` or `del`.

For templates: read current template, identify variables, create backup, prepare minimal patch, validate, save after approval and re-read.

For orders and checkout: default to read-only diagnostics. Do not submit orders or change statuses without explicit confirmation.

### 8. Produce final report

Return:

- selected scope;
- completed changes;
- API endpoints used;
- skipped risky changes;
- protected fields untouched;
- validation status;
- rollback notes;
- image files/endpoints used, if relevant;
- next recommended step.

## Standard output format

### Scope confirmation

- Scope:
- Objects:
- Mode: read-only / write preview / apply approved changes
- Batch size:

### Shop audit summary

- Site/module checked:
- Categories checked:
- Products checked:
- Templates checked:
- Visual assets checked:
- Critical issues:
- High-priority issues:
- Medium/low issues:
- Recommended first batch:

### Change plan

| Priority | Object | Endpoint/field | Issue | Proposed fix | Protected fields | Risk |
|---|---|---|---|---|---|---|

### Product/category preview

| Object | Current value | Proposed value | Field | Apply? |
|---|---|---|---|---|

### Image plan preview

| Object | Image operation | Endpoint | Request fields | Output | Replace current? |
|---|---|---|---|---|---|

### Final report

- Scope:
- Changed:
- Not changed:
- API endpoints used:
- Protected fields:
- Validation:
- Rollback:
- Next step:

## Prompt examples

- “Audit my uCoz shop and show which categories and product cards should be improved first.”
- “Find categories with empty descriptions and suggest SEO copy. Do not change URLs.”
- “Prepare 20 product cards: name, short description and full description. Do not touch prices or stock.”
- “For products in category 15, generate and add images through the API. Do not replace existing photos.”
- “Replace the first image for product 123 with a new one. Show a preview first.”
- “Add Product Schema to the product template, but show the plan first and check available variables.”
- “Check whether price, old price, availability and add-to-cart button display correctly.”
- “Generate an order report: new, paid, cancelled and archived orders. Do not change statuses.”
- “Create a new category and 5 products from this list. Keep products hidden for now.”
- “Check checkout and cart as a test buyer. Do not submit a real order.”

## Safety rules

- Never expose API tokens, FTP credentials or private configuration values.
- Never ask for API key if it is available from `ucoz-mcp`.
- Never use a site other than the active site from `ucoz-mcp` unless the user explicitly switches site context.
- Never change commercial fields without explicit approval: price, old price, purchase price, stock, SKU/article, product type, variations, currency rate.
- Never change operational fields without explicit approval: order status, courier, order items, order fields, order notes, order group/archive/trash state.
- Never delete products, categories, orders, files, templates, product images or cart contents unless explicitly requested.
- Never clear a basket unless the user explicitly asked to clear it.
- Never submit a real order without explicit confirmation.
- Never update legal, warranty, return, delivery or payment text unless explicitly requested.
- Never hide public categories or products automatically.
- Never replace existing product or category images automatically.
- Never use FTP as the primary product-image upload path.
- Never use `del_imgN` as the general product-image mechanism.
- Never claim a generated concept is the exact real product photo if the appearance is unknown.
- Never invent logos, packaging artwork, certificates or precise product specs.
- Never mass-update more than 20 items without a preview and batch plan.
- Always validate template changes before saving.
- Always keep rollback notes for template and FTP/template changes.