craft-cms-skills

name	Craft CMS Skills
description	Complete skill suite for managing Craft CMS content including users, addresses, sections, entry types, fields, entries, drafts, field layouts, sites, and Commerce products, variants, and orders.

Important: Use this plugin, Not YAML Files

CRITICAL: Always use this HTTP API to manage Craft CMS content. Never directly modify YAML configuration files in the config/project/ directory. The API ensures proper validation, maintains data integrity, and handles all necessary relationships automatically. Direct YAML edits can corrupt your Craft installation.

CRITICAL: The skills plugin must be installed to Craft. You can verify installation by running php craft plugin/list and install it with php craft plugin/install skills

Base URL Configuration

All API routes require a base URL and API prefix. The standard Craft CMS configuration uses the PRIMARY_SITE_URL environment variable and a configurable API prefix:

• Environment Variable: Check for PRIMARY_SITE_URL in ENV or .env file
• If Not Set: Ask the user for the base URL to use
• API Prefix: Configurable prefix that defaults to /api
  • Check Order:
    1. First check config/skills.php for apiPrefix in the PHP array
    2. If not found, try the default /api
    3. If requests fail, ask the user for the configured API prefix
• Route Format: {PRIMARY_SITE_URL}/{apiPrefix}/{endpoint}
• Default Example: https://craft-site.com/api/sections
• Custom Prefix Example: https://craft-site.com/custom-api/sections

Request/Response Format

All API endpoints:

• Return JSON: All responses are in JSON format with structured data
• Accept Header: Include Accept: application/json header in requests to ensure errors are also formatted as JSON for better error handling and debugging
• Content-Type: Use Content-Type: application/json for POST/PUT requests with JSON body data

Content

• create_entry - POST /api/entries - Create entries with section/entry type IDs and field data
• get_entry - GET /api/entries/<id> - Retrieve entry by ID with all fields and metadata
• update_entry - PUT /api/entries/<id> - Update entry (prefers draft workflow)
• delete_entry - DELETE /api/entries/<id> - Delete entry (soft/permanent)
• search_content - GET /api/entries/search - Search/filter entries by section/status/query

Drafts

• create_draft - POST /api/drafts - Create draft from scratch or existing entry
• update_draft - PUT /api/drafts/<id> - Update draft content/metadata (PATCH semantics)
• apply_draft - POST /api/drafts/<id>/apply - Publish draft to canonical entry

Sections

• create_section - POST /api/sections - Create section with types/versioning/sites
• get_sections - GET /api/sections - List all or filter by IDs
• update_section - PUT /api/sections/<id> - Update properties/settings
• delete_section - DELETE /api/sections/<id> - Permanently delete (removes all entries)

Entry Types

• create_entry_type - POST /api/entry-types - Create with handle/name/layout
• get_entry_types - GET /api/entry-types - List with fields/usage/URLs
• update_entry_type - PUT /api/entry-types/<id> - Update properties/layout
• delete_entry_type - DELETE /api/entry-types/<id> - Delete if not in use

Fields

• create_field - POST /api/fields - Create with type and settings
• get_fields - GET /api/fields - List global or layout-specific
• get_field_types - GET /api/fields/types - List available types
• update_field - PUT /api/fields/<id> - Update properties/settings
• delete_field - DELETE /api/fields/<id> - Permanently delete (removes data)

Field Layouts

• create_field_layout - POST /api/field-layouts - Create empty field layout for entry types
• get_field_layout - GET /api/field-layouts - Get field layout structure by entry type/layout/element ID
• add_tab_to_field_layout - POST /api/field-layouts/<id>/tabs - Add tab to field layout with flexible positioning (prepend/append/before/after)
• add_field_to_field_layout - POST /api/field-layouts/<id>/fields - Add custom field to tab with positioning, width, required, and display options
• add_ui_element_to_field_layout - POST /api/field-layouts/<id>/ui-elements - Add UI elements (heading, tip, horizontal rule, markdown, template) to layouts
• move_element_in_field_layout - PUT /api/field-layouts/<id>/elements - Move fields/UI elements within or between tabs with precise positioning
• remove_element_from_field_layout - DELETE /api/field-layouts/<id>/elements - Remove fields or UI elements from field layout

Sites

• get_sites - GET /api/sites - List all sites with IDs/handles/URLs

Assets

• create_asset - POST /api/assets - Upload file from local/remote URL to volume
• update_asset - PUT /api/assets/<id> - Update metadata or replace file
• delete_asset - DELETE /api/assets/<id> - Delete asset and file
• get_volumes - GET /api/volumes - List asset volumes with IDs/URLs

Addresses

• get_addresses - GET /api/addresses - List/search addresses by owner, field, and location
• get_address - GET /api/addresses/<id> - Retrieve address details with owner and field context
• create_address - POST /api/addresses - Create generic owner-backed addresses for users or custom address fields
• update_address - PUT /api/addresses/<id> - Update address attributes and custom fields
• delete_address - DELETE /api/addresses/<id> - Delete address (soft/permanent)
• get_address_field_layout - GET /api/addresses/field-layout - Retrieve the single global address field layout

Users

• get_users - GET /api/users - List/search users by query, identity fields, status, and optionally group
• get_user - GET /api/users/<id> - Retrieve a user by ID, email, or username
• create_user - POST /api/users - Create a user with native attributes and custom fields
• get_available_permissions - GET /api/users/permissions - List all known permissions plus custom stored permission names
• update_user - PUT /api/users/<id> - Update a user by ID, email, or username
• delete_user - DELETE /api/users/<id> - Delete a user by ID, email, or username
• get_user_field_layout - GET /api/users/field-layout - Retrieve the single global user field layout

User Groups

• get_user_groups - GET /api/user-groups - List user groups and their permissions
• get_user_group - GET /api/user-groups/<id> - Retrieve a user group by ID or handle
• create_user_group - POST /api/user-groups - Create a user group and set permissions
• update_user_group - PUT /api/user-groups/<id> - Update a user group and its permissions
• delete_user_group - DELETE /api/user-groups/<id> - Delete a user group by ID or handle

System

• health - GET /api/health - Health check endpoint to verify plugin installation and API availability

Commerce: Products

• create_product - POST /api/products - Create product with type, title, SKU, price, and custom fields
• get_product - GET /api/products/<id> - Retrieve product with variants, pricing, and custom fields
• get_products - GET /api/products/search - Search/filter products by type/status/query
• update_product - PUT /api/products/<id> - Update product attributes and custom fields
• delete_product - DELETE /api/products/<id> - Delete product (soft/permanent)
• get_product_types - GET /api/product-types - List available Commerce product types
• get_product_type - GET /api/product-types/<id> - Retrieve product type with field layouts and site settings
• create_product_type - POST /api/product-types - Create product type with title, variant, layout, and site settings
• update_product_type - PUT /api/product-types/<id> - Update product type configuration and site settings
• delete_product_type - DELETE /api/product-types/<id> - Delete product type with impact analysis and force protection

Commerce: Variants

• create_variant - POST /api/variants - Add variant to existing product with SKU, price, and attributes
• get_variant - GET /api/variants/<id> - Retrieve variant with pricing, inventory, and dimensions
• update_variant - PUT /api/variants/<id> - Update variant pricing, SKU, stock, and fields
• delete_variant - DELETE /api/variants/<id> - Delete variant (soft/permanent)

Commerce: Orders

• get_order - GET /api/orders/<id> - Retrieve order with line items, totals, and addresses
• search_orders - GET /api/orders/search - Search/filter orders by email/status/date/payment
• update_order - PUT /api/orders/<id> - Update order status or message
• get_order_statuses - GET /api/order-statuses - List all order statuses with IDs/handles/colors

Commerce: Stores

• get_stores - GET /api/stores - List all stores with checkout/payment/tax configuration
• get_store - GET /api/stores/<id> - Retrieve store with full configuration details
• update_store - PUT /api/stores/<id> - Update store checkout, payment, and pricing settings